location/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/location-types.h>
  26
  27 G_BEGIN_DECLS
  28
  29 /**
  30  * @file location-accuracy.h
  31  * @brief This file contains the definitions, structures, and functions related to accuracy information.
  32  * @addtogroup LocationTypes
  33  * @{
  34  */
  35
  36 /**
  37  * @brief This represents the approximate accuracy level of given information.
  38  */
  39 typedef enum {
  40         LOCATION_ACCURACY_LEVEL_NONE = 0,    ///< Invalid data.
  41         LOCATION_ACCURACY_LEVEL_COUNTRY,     ///< Country accuracy level->
  42         LOCATION_ACCURACY_LEVEL_REGION,      ///< Regional accuracy level->
  43         LOCATION_ACCURACY_LEVEL_LOCALITY,    ///< Local accuracy level->
  44         LOCATION_ACCURACY_LEVEL_POSTALCODE,  ///< Postal accuracy level->
  45         LOCATION_ACCURACY_LEVEL_STREET,      ///< Street accuracy level->
  46         LOCATION_ACCURACY_LEVEL_DETAILED,    ///< Detailed accuracy level->
  47 } LocationAccuracyLevel;
  48
  49 /**
  50  * @brief This represents location accuracy information such as accuracy level, horizontal and vertical accuracy.
  51  */
  52 struct _LocationAccuracy
  53 {
  54         LocationAccuracyLevel level;        ///< The accuracy level of the location information.
  55         gdouble horizontal_accuracy;        ///< The horizontal position uncertainty  of the location in meters.
  56         gdouble vertical_accuracy;          ///< The vertical position uncertainty of the location in meters.
  57 };
  58
  59 GType location_accuracy_get_type(void);
  60 #define LOCATION_TYPE_ACCURACY (location_accuracy_get_type())
  61
  62 /**
  63  * @brief   Create a new #LocationAccuracy with  given information.
  64  * @remarks None.
  65  * @pre     #location_init should be called before.\n
  66  * @post    None.
  67  * @param [in]  level - The accuracy level of the location information.
  68  * @param [in]  horizontal_accuracy - The horizontal position uncertainty  of the location in meters.
  69  * @param [in]  vertical_accuracy - The vertical position uncertainty of the location in meters.
  70  * @return a new #LocationAccuracy
  71  * @retval NULL if error occured
  72  */
  73 LocationAccuracy *location_accuracy_new (LocationAccuracyLevel level, gdouble horizontal_accuracy, gdouble vertical_accuracy);
  74
  75 /**
  76  * @brief   Free a #LocationAccuracy.
  77  * @remarks None.
  78  * @pre     #location_init should be called before.\n
  79  * @post    None.
  80  * @param [in] accuracy - a #LocationAccuracy.
  81  * @return None.
  82  */
  83 void location_accuracy_free (LocationAccuracy *accuracy);
  84
  85 /**
  86  * @brief   Compare for two accuracys.
  87  * @remarks None.
  88  * @pre     #location_init should be called before.\n
  89  * @post    None.
  90  * @param [in]  accuracy1 - a #LocationAccuracy
  91  * @param [in]  accuracy2 - another #LocationAccuracy
  92  * @return integer
  93  * @retval\n
  94  * 0 - if the accuracy match\n
  95  * positive value - if accuracy of accuracy1 is better than accuracy of accuracy2\n
  96  * negative value - if accuracy of accuracy1 is worse than accuracy of accuracy2
  97  */
  98 int location_accuracy_compare (const LocationAccuracy *accuracy1, const LocationAccuracy *accuracy2);
  99
 100 /**
 101  * @brief   Compare for two accuracys' level.
 102  * @remarks None.
 103  * @pre     #location_init should be called before.\n
 104  * @post    None.
 105  * @param [in]  accuracy1 - a #LocationAccuracy
 106  * @param [in]  accuracy2 - another #LocationAccuracy
 107  * @return integer
 108  * @retval\n
 109  * 0 - if the accuracy match\n
 110  * positive value - if accuracy1's level is better than accuracy2's level\n
 111  * negative value - if accuracy1's level is worse than accuracy2's level
 112  */
 113 int location_accuracy_level_compare(const LocationAccuracy *accuracy1, const LocationAccuracy *accuracy2);
 114
 115 /**
 116  * @brief   Makes a copy of #LocationAccuracy
 117  * @remarks None.
 118  * @pre     #location_init should be called before.\n
 119  * @post    None.
 120  * @param [in]  accuracy - a #LocationAccuracy
 121  * @return a new #LocationAccuracy
 122  * @retval NULL if error occured
 123  */
 124 LocationAccuracy *location_accuracy_copy (const LocationAccuracy *accuracy);
 125
 126 /**
 127  * @}
 128  */
 129
 130 G_END_DECLS
 131
 132 #endif