location/manager/location-satellite.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 #ifndef __LOCATION_SATELLITE_H_
  20 #define __LOCATION_SATELLITE_H_
  21
  22 #include <location-types.h>
  23
  24 G_BEGIN_DECLS
  25
  26 GType location_satellite_get_type(void);
  27 #define LOCATION_TYPE_SATELLITE (location_satellite_get_type())
  28
  29 /**
  30  * @file location-satellite.h
  31  * @brief This file contains the internal definitions and structures related to satellite information.
  32  */
  33 /**
  34  * @addtogroup LocationAPI
  35  * @{
  36  * @defgroup LocationAPISatellite Location Satellite
  37  * @breif This provides APIs related to Location Satellite
  38  * @addtogroup LocationAPISatellite
  39  * @{
  40  */
  41
  42 /**
  43  * @brief This represents one satellite information in view.
  44  */
  45 typedef struct {
  46         guint prn;                      /*/< The PRNs(Pseudo-Random Noise code) of a satellite. */
  47         gboolean used;          /*/< TRUE if currently used satellite. */
  48         guint elevation;        /*/< The elevation of a satellite. */
  49         guint azimuth;          /*/< The degree from true north 000 to 359 of a satellite. */
  50         gint snr;                       /*/< The signal-to-noise ratio, dB of a satellite. */
  51 } LocationSatelliteDetail;
  52
  53 /**
  54  * @brief This represents position information such as number of satellites in used or in view.
  55  */
  56 struct _LocationSatellite {
  57         guint timestamp;                                                        /*/< Time stamp. */
  58         guint num_of_sat_inview;                                        /*/< The number of satellites in view. */
  59         guint num_of_sat_used;                                          /*/< The number of satellites in used. */
  60         LocationSatelliteDetail *sat_inview;            /*/< The information of satellites in view . */
  61 };
  62
  63 /**
  64  * @brief       Create a new #LocationSatellite with given number of #LocationSatelliteDetail.
  65  * @remarks None.
  66  * @pre  #location_init should be called before.\n
  67  * @post        None.
  68  * @param [in] num_of_sat_inview - number of #LocationSatelliteDetail.
  69  * @return a new #LocationSatellite
  70  * @retval NULL if error occured
  71  */
  72 LocationSatellite *location_satellite_new(int num_of_sat_inview);
  73
  74 /**
  75  * @brief       Free a #LocationSatellite.
  76  * @remarks None.
  77  * @pre  #location_init should be called before.\n
  78  * @post        None.
  79  * @param [in] satellite - a #LocationSatellite.
  80  * @return None.
  81  */
  82 void location_satellite_free(LocationSatellite *satellite);
  83
  84 /**
  85  * @brief       Makes a copy of #LocationSatellite
  86  * @remarks None.
  87  * @pre  #location_init should be called before.\n
  88  * @post        None.
  89  * @param [in] satellite - a #LocationSatellite
  90  * @return a new #LocationSatellite
  91  * @retval NULL if error occured
  92  */
  93 LocationSatellite *location_satellite_copy(const LocationSatellite *satellite);
  94
  95 /**
  96  * @brief       Get elements of #LocationSatelliteDetail with given index in #LocationSatellite.
  97  * @remarks None.
  98  * @pre  #location_init should be called before.\n
  99  * @post        None.
 100  * @param [in]  satellite - a #LocationSatellite
 101  * @param [in]  index - index of #LocationSatelliteDetail in #LocationSatellite
 102  * @param [out] prn - The PRNs(Pseudo-Random Noise code) of a #LocationSatellite
 103  * @param [out] used - TRUE if a #LocationSatellite in used.
 104  * @param [out] elevation - The elevation of a #LocationSatellite
 105  * @param [out] azimuth - The degree from true north 000 to 359 of a#LocationSatellite
 106  * @param [out] snr - The signal-to-noise ratio, dB of #LocationSatellite
 107  * @return gboolean
 108  * @retval\n
 109  * TRUE - if success\n
 110  * FALSE - if error occured\n
 111  */
 112 gboolean location_satellite_get_satellite_details(const LocationSatellite *satellite, guint index, guint *prn, gboolean *used, guint *elevation, guint *azimuth, gint *snr);
 113
 114 /**
 115  * @brief       Set elements of #LocationSatelliteDetail with given index in #LocationSatellite.
 116  * @remarks None.
 117  * @pre  #location_init should be called before.\n
 118  * @post        None.
 119  * @param [in]  satellite - a #LocationSatellite
 120  * @param [in]  index - index of #LocationSatelliteDetail in #LocationSatellite
 121  * @param [in]  prn - The PRNs(Pseudo-Random Noise code) of a #LocationSatellite
 122  * @param [in]  used - TRUE if a #LocationSatellite in used.
 123  * @param [in]  elevation - The elevation of a #LocationSatellite
 124  * @param [in]  azimuth - The degree from true north 000 to 359 of a#LocationSatellite
 125  * @param [in]  snr - The signal-to-noise ratio, dB of #LocationSatellite
 126  * @return gboolean
 127  * @retval\n
 128  * TRUE - if success\n
 129  * FALSE - if error occured\n
 130  */
 131 gboolean location_satellite_set_satellite_details(LocationSatellite *satellite, guint index, guint prn, gboolean used, guint elevation, guint azimuth, gint snr);
 132
 133 /**
 134  * @} @}
 135  */
 136
 137 G_END_DECLS
 138
 139 #endif