location/location-poi-info.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_POI_INFO_H__
  23 #define __LOCATION_POI_INFO_H__
  24
  25 #include <location/location-types.h>
  26 #include <location/location-position.h>
  27 #include <location/location-address.h>
  28
  29 /**
  30  * @file location-poi-info.h
  31  * @brief This file contains the internal definitions and structures related to POI information.
  32  * @addtogroup LocationTypes
  33  * @{
  34  */
  35
  36 G_BEGIN_DECLS
  37
  38 /**
  39  * @brief This represents one POI information such as name, type of POI, etc.
  40  */
  41 typedef struct _LocationPOIDetail {
  42         gchar *name;                   // Name of a POI
  43         gchar *type;                   // Type of a POI (e.g. cafe)
  44         LocationAddress *address;      // Address of a POI
  45         LocationPosition *position;    // Position of a POI
  46         gchar *phone_number;           // Phone number of a POI
  47         GHashTable *properties;        // GHashTable with detailed characteristics of a POI.
  48 } LocationPOIDetail;
  49
  50 /**
  51  * @brief This represents a number of POI informations.
  52  */
  53 struct _LocationPOIInfo
  54 {
  55         guint num_of_poi;
  56         LocationPOIDetail *poi_detail;
  57 };
  58
  59 GType location_poiinfo_get_type (void);
  60 #define LOCATION_TYPE_POIINFO (location_poiinfo_get_type ())
  61
  62 /**
  63  * @brief   Create a new GHashTable for properties in a #LocationPOIDetail.
  64  * @remarks None.
  65  * @pre     #location_init should be called before.\n
  66  * @post    None.
  67  * @param   None.
  68  * @return  a new GHashTable.
  69  * @retval  NULL if error occured
  70  */
  71 GHashTable *location_poiinfo_detail_properties_new (void);
  72
  73 /**
  74  * @brief   Free a GHashTable for properties in a #LocationPOIDetail.
  75  * @remarks None.
  76  * @pre     #location_init should be called before.\n
  77  * @post    None.
  78  * @param [in] properties - a #GHashTable.
  79  * @return None.
  80  */
  81 void location_poiinfo_detail_properties_free (GHashTable* properties);
  82
  83 /**
  84  * @brief   Insert a new key and value into a GHashTable for properties in a #LocationPOIDetail.
  85  * @remarks None.
  86  * @pre     #location_init should be called before.\n
  87  * @post    None.
  88  * @param [in]  properties - a #GHashTable in a #LocationPOIDetail.
  89  * @param [in]  key - a key to insert (e.g. URL)
  90  * @param [in]  value - the value to associate with the key. (e.g. http://www.samsung.com)
  91  * @return gboolean
  92  * @retval\n
  93  * TRUE - if success\n
  94  * FALSE - if error occured\n
  95  */
  96 gboolean location_poiinfo_detail_properties_insert (GHashTable* properties, const gchar* key, const gchar* value);
  97
  98 /**
  99  * @brief   Makes a copy of GHashTable for properties in a #LocationPOIDetail.
 100  * @remarks None.
 101  * @pre     #location_init should be called before.\n
 102  * @post    None.
 103  * @param [in]  properties - a #GHashTable
 104  * @return a new #GHashTable
 105  * @retval NULL if error occured
 106  */
 107 GHashTable *location_poiinfo_detail_properties_copy (const GHashTable *properties);
 108
 109 /**
 110  * @brief   Create a new #LocationPOIInfo with given number of #LocationPOIDetail.
 111  * @remarks None.
 112  * @pre     #location_init should be called before.\n
 113  * @post    None.
 114  * @param [in]  num_of_poi - number of #LocationPOIDetail.
 115  * @return a new #LocationPOIInfo
 116  * @retval NULL if error occured
 117  */
 118 LocationPOIInfo* location_poiinfo_new (int num_of_poi);
 119
 120 /**
 121  * @brief   Free a #LocationPOIInfo.
 122  * @remarks None.
 123  * @pre     #location_init should be called before.\n
 124  * @post    None.
 125  * @param [in] poi_info - a #LocationPOIInfo.
 126  * @return None.
 127  */
 128 void location_poiinfo_free(LocationPOIInfo* poi_info);
 129
 130 /**
 131  * @brief   Makes a copy of #LocationPOIInfo
 132  * @remarks None.
 133  * @pre     #location_init should be called before.\n
 134  * @post    None.
 135  * @param [in]  poi_info - a #LocationPOIInfo
 136  * @return a new #LocationPOIInfo
 137  * @retval NULL if error occured
 138  */
 139 LocationPOIInfo *location_poiinfo_copy (const LocationPOIInfo* poi_info);
 140
 141 /**
 142  * @brief   Get elements of #LocationPOIDetail with given index in #LocationPOIInfo.
 143  * @remarks None.
 144  * @pre     #location_init should be called before.\n
 145  * @post    None.
 146  * @param [in]   poi_info - a #LocationPOIInfo
 147  * @param [in]   index - index of #LocationPOIDetail in #LocationPOIInfo
 148  * @param [out]  name - a name of a #LocationPOIDetail
 149  * @param [out]  type - a type of a #LocationPOIDetail
 150  * @param [out]  address - a address of a #LocationPOIDetail
 151  * @param [out]  position - a position of a#LocationPOIDetail
 152  * @param [out]  phone_number - a phone number of #LocationPOIDetail
 153  * @param [out]  properties - a GHashTable with properties of #LocationPOIDetail
 154  * @return gboolean
 155  * @retval\n
 156  * TRUE - if success\n
 157  * FALSE - if error occured\n
 158  */
 159 gboolean location_poiinfo_get_poi_detail(LocationPOIInfo *poi_info, guint index, gchar** name, gchar** type, LocationAddress** address, LocationPosition** position, gchar** phone_number, GHashTable** properties);
 160
 161 /**
 162  * @brief   Set elements of #LocationPOIDetail with given index in #LocationPOIInfo.
 163  * @remarks None.
 164  * @pre     #location_init should be called before.\n
 165  * @post    None.
 166  * @param [in]  poi_info - a #LocationPOIInfo
 167  * @param [in]  index - index of #LocationPOIDetail in #LocationPOIInfo
 168  * @param [in]  name - a name of a #LocationPOIDetail
 169  * @param [in]  type - a type of a #LocationPOIDetail
 170  * @param [in]  address - a address of a #LocationPOIDetail
 171  * @param [in]  position - a position of a #LocationPOIDetail
 172  * @param [in]  phone_number - a phone number of a #LocationPOIDetail
 173  * @param [in]  properties - a GHashTable with properties of a #LocationPOIDetail, can be NULL if a POI have no additional properties
 174  * @return gboolean
 175  * @retval\n
 176  * TRUE - if success\n
 177  * FALSE - if error occured\n
 178  */
 179 gboolean location_poiinfo_set_poi_detail(LocationPOIInfo *poi_info, guint index, const gchar* name, const gchar* type, const LocationAddress* address, const LocationPosition* position, const gchar* phone_number, const GHashTable* properties);
 180
 181 /**
 182  * @}
 183  */
 184
 185 G_END_DECLS
 186
 187 #endif