location/manager/location-accuracy.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Youngae Kang <youngae.kang@samsung.com>, Yunhan Kim <yhan.kim@samsung.com>,
   7  *          Genie Kim <daejins.kim@samsung.com>, Minjune Kim <sena06.kim@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  */
  21
  22 #ifndef __LOCATION_ACCURACY_H_
  23 #define __LOCATION_ACCURACY_H_
  24
  25 #include <location-types.h>
  26
  27 G_BEGIN_DECLS
  28
  29 GType location_accuracy_get_type(void);
  30 #define LOCATION_TYPE_ACCURACY (location_accuracy_get_type())
  31
  32 /**
  33  * @file location-accuracy.h
  34  * @brief This file contains the definitions, structures, and functions related to accuracy information.
  35  */
  36
  37 /**
  38  * @addtogroup LocationAPI
  39  * @{
  40  * @defgroup LocationAPIAccuracy Location Accuracy
  41  * @breif This provides APIs related to Location Accuracy.
  42  * @addtogroup LocationAPIAccuracy
  43  * @{
  44  */
  45
  46 /**
  47  * @brief This represents the approximate accuracy level of given information.
  48  */
  49 typedef enum {
  50         LOCATION_ACCURACY_LEVEL_NONE = 0,    ///< Invalid data.
  51         LOCATION_ACCURACY_LEVEL_COUNTRY,     ///< Country accuracy level->
  52         LOCATION_ACCURACY_LEVEL_REGION,      ///< Regional accuracy level->
  53         LOCATION_ACCURACY_LEVEL_LOCALITY,    ///< Local accuracy level->
  54         LOCATION_ACCURACY_LEVEL_POSTALCODE,  ///< Postal accuracy level->
  55         LOCATION_ACCURACY_LEVEL_STREET,      ///< Street accuracy level->
  56         LOCATION_ACCURACY_LEVEL_DETAILED,    ///< Detailed accuracy level->
  57 } LocationAccuracyLevel;
  58
  59 /**
  60  * @brief This represents location accuracy information such as accuracy level, horizontal and vertical accuracy.
  61  */
  62 struct _LocationAccuracy
  63 {
  64         LocationAccuracyLevel level;        ///< The accuracy level of the location information.
  65         gdouble horizontal_accuracy;        ///< The horizontal position uncertainty  of the location in meters.
  66         gdouble vertical_accuracy;          ///< The vertical position uncertainty of the location in meters.
  67 };
  68
  69 /**
  70  * @brief   Create a new #LocationAccuracy with  given information.
  71  * @remarks None.
  72  * @pre     #location_init should be called before.\n
  73  * @post    None.
  74  * @param [in]  level - The accuracy level of the location information.
  75  * @param [in]  horizontal_accuracy - The horizontal position uncertainty  of the location in meters.
  76  * @param [in]  vertical_accuracy - The vertical position uncertainty of the location in meters.
  77  * @return a new #LocationAccuracy
  78  * @retval NULL if error occured
  79  */
  80 LocationAccuracy *location_accuracy_new (LocationAccuracyLevel level, gdouble horizontal_accuracy, gdouble vertical_accuracy);
  81
  82 /**
  83  * @brief   Free a #LocationAccuracy.
  84  * @remarks None.
  85  * @pre     #location_init should be called before.\n
  86  * @post    None.
  87  * @param [in] accuracy - a #LocationAccuracy.
  88  * @return None.
  89  */
  90 void location_accuracy_free (LocationAccuracy *accuracy);
  91
  92 /**
  93  * @brief   Compare for two accuracys.
  94  * @remarks None.
  95  * @pre     #location_init should be called before.\n
  96  * @post    None.
  97  * @param [in]  accuracy1 - a #LocationAccuracy
  98  * @param [in]  accuracy2 - another #LocationAccuracy
  99  * @return integer
 100  * @retval\n
 101  * 0 - if the accuracy match\n
 102  * positive value - if accuracy of accuracy1 is better than accuracy of accuracy2\n
 103  * negative value - if accuracy of accuracy1 is worse than accuracy of accuracy2
 104  */
 105 int location_accuracy_compare (const LocationAccuracy *accuracy1, const LocationAccuracy *accuracy2);
 106
 107 /**
 108  * @brief   Compare for two accuracys' level.
 109  * @remarks None.
 110  * @pre     #location_init should be called before.\n
 111  * @post    None.
 112  * @param [in]  accuracy1 - a #LocationAccuracy
 113  * @param [in]  accuracy2 - another #LocationAccuracy
 114  * @return integer
 115  * @retval\n
 116  * 0 - if the accuracy match\n
 117  * positive value - if accuracy1's level is better than accuracy2's level\n
 118  * negative value - if accuracy1's level is worse than accuracy2's level
 119  */
 120 int location_accuracy_level_compare(const LocationAccuracy *accuracy1, const LocationAccuracy *accuracy2);
 121
 122 /**
 123  * @brief   Makes a copy of #LocationAccuracy
 124  * @remarks None.
 125  * @pre     #location_init should be called before.\n
 126  * @post    None.
 127  * @param [in]  accuracy - a #LocationAccuracy
 128  * @return a new #LocationAccuracy
 129  * @retval NULL if error occured
 130  */
 131 LocationAccuracy *location_accuracy_copy (const LocationAccuracy *accuracy);
 132
 133 /**
 134  * @} @}
 135  */
 136
 137 G_END_DECLS
 138
 139 #endif