include/maps_area.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 #ifndef __MAPS_GEOAREA_H__
  18 #define __MAPS_GEOAREA_H__
  19
  20 #include <maps_coordinates.h>
  21
  22 /**
  23  * @ingroup     CAPI_MAPS_SERVICE_MODULE
  24  * @defgroup    CAPI_MAPS_GEOAREA_MODULE Area
  25  *
  26  * @file maps_area.h
  27  * @brief This file contains the definitions, structures, and functions related
  28  * to area information.
  29  *
  30  * @addtogroup CAPI_MAPS_GEOAREA_MODULE
  31  * @{
  32  * @brief This provides APIs related to geographical area.
  33  */
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  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().
  43  * @since_tizen 2.4
  44  * \n To release the handle use maps_area_destroy().
  45  * \n To clone the handle use maps_area_clone().
  46  * @since_tizen 2.4
  47  *
  48  * @see maps_area_create_rectangle()
  49  * @see maps_area_create_circle()
  50  * @see maps_area_destroy()
  51  * @see maps_area_clone()
  52  */
  53 typedef void *maps_area_h;
  54
  55 /**
  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.
  60  * @since_tizen 2.4
  61  *
  62  * @see maps_area_s
  63  */
  64 typedef enum {
  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. */
  68 } maps_area_type_e;
  69
  70 /**
  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.
  75  * @since_tizen 2.4
  76  *
  77  * @see maps_area_s
  78  */
  79 typedef struct _maps_area_rectangle_s {
  80         maps_coordinates_s top_left;            /**< The top left position
  81                                                   of rectangle. */
  82         maps_coordinates_s bottom_right;        /**< The bottom right position
  83                                                   of rectangle. */
  84 } maps_area_rectangle_s;
  85
  86 /**
  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.
  91  * @since_tizen 2.4
  92  *
  93  * @see maps_area_s
  94  */
  95 typedef struct _maps_area_circle_s {
  96
  97         maps_coordinates_s center;      /**< The center position of a circle. */
  98         double radius;                  /**< The radius of a circle. */
  99 } maps_area_circle_s;
 100
 101 /**
 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.
 105  * @since_tizen 2.4
 106  *
 107  * @see maps_area_type_e
 108  * @see maps_area_rectangle_s
 109  * @see maps_area_circle_s
 110  */
 111 typedef struct _maps_area_s {
 112         maps_area_type_e type;  /**< The area type of this information. */
 113         union {
 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. */
 118         };
 119 } maps_area_s;
 120
 121 /*----------------------------------------------------------------------------*/
 122
 123 /**
 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.
 128  * @since_tizen 2.4
 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().
 133  *
 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
 141  *
 142  * @pre @a top_left and @a bottom_right are created using
 143  * maps_coordinates_create().
 144  *
 145  * @see maps_area_clone()
 146  * @see maps_area_destroy()
 147  * @see maps_area_create_circle()
 148  * @see maps_area_s
 149  * @see maps_coordinates_create()
 150  * @see maps_coordinates_destroy()
 151  */
 152 int maps_area_create_rectangle(const maps_coordinates_h top_left,
 153                                const maps_coordinates_h bottom_right,
 154                                maps_area_h *area);
 155
 156 /**
 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.
 161  * @since_tizen 2.4
 162  * @remarks @a area must be released using maps_area_destroy().
 163  * \n @a top_left and @a bottom_right must be released using
 164  * maps_coordinates_destroy().
 165  *
 166  * @param[in]   center          The central position of the area
 167  * @param[in]   radius          The radius of the area
 168  * @param[out]  area            The area handle
 169  * @return      0 on success, otherwise a negative error value
 170  * @retval      #MAPS_ERROR_NONE Successful
 171  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 172  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 173  *
 174  * @pre @a center is created using maps_coordinates_create().
 175  *
 176  * @see maps_area_clone()
 177  * @see maps_area_destroy()
 178  * @see maps_area_create_rectangle()
 179  * @see maps_area_s
 180  * @see maps_coordinates_create()
 181  * @see maps_coordinates_destroy()
 182  */
 183 int maps_area_create_circle(const maps_coordinates_h center,
 184                             const double radius, maps_area_h *area);
 185
 186 /**
 187  * @brief       Destroys the Geographical Area and releases all its resources.
 188  * @details This function destroys the Geographical Area #maps_area_s and
 189  * releases all its resources.
 190  * @since_tizen 2.4
 191  *
 192  * @param[in]   area            The area #maps_area_s
 193  * @return      0 on success, otherwise a negative error value
 194  * @retval      #MAPS_ERROR_NONE Successful
 195  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 196  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 197  *
 198  * @pre @a area can be created using maps_area_create_rectangle() or
 199  * maps_area_create_circle().
 200  *
 201  * @see maps_area_create_rectangle()
 202  * @see maps_area_create_circle()
 203  */
 204 int maps_area_destroy(maps_area_h area);
 205
 206 /**
 207  * @brief       Clones the Geographical Area.
 208  * @details This function makes a clone of the @a origin Geographical Area of
 209  * type #maps_area_s.
 210  * @since_tizen 2.4
 211  * @remarks @a cloned must be released using maps_area_destroy().
 212  *
 213  * @param[in]   origin          The area #maps_area_s to be copied
 214  * @param[out]  cloned          The cloned area #maps_area_s handle
 215  * @return      0 on success, otherwise a negative error value
 216  * @retval      #MAPS_ERROR_NONE Successful
 217  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 218  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 219  *
 220  * @pre @a origin is created using maps_area_create_rectangle() or
 221  * maps_area_create_circle().
 222  *
 223  * @see maps_area_create_rectangle()
 224  * @see maps_area_create_circle()
 225  * @see maps_area_destroy()
 226  * @see maps_area_s
 227  */
 228 int maps_area_clone(const maps_area_h origin, maps_area_h *cloned);
 229
 230 #ifdef __cplusplus
 231 }
 232 #endif
 233 /**
 234  * @}
 235  */
 236 #endif                          /* __MAPS_GOEAREA_H__ */