include/telephony_network.h

   1 /*
   2  * Copyright (c) 2011 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 __CAPI_TELEPHONY_NETWORK_INFO_H__
  18 #define __CAPI_TELEPHONY_NETWORK_INFO_H__
  19
  20 #include "telephony_common.h"
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 /**
  28  * @file telephony_network.h
  29  * @brief This file contains the network APIs and related enumerations.
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_TELEPHONY_INFORMATION_NETWORK
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Enumeration for RSSI (Receive Signal Strength Indicator).
  39  * @details #TELEPHONY_NETWORK_RSSI_6 indicates the highest strength.
  40  * @since_tizen 2.3
  41  */
  42 typedef enum
  43 {
  44     TELEPHONY_NETWORK_RSSI_0, /**< Strength 0 */
  45     TELEPHONY_NETWORK_RSSI_1, /**< Strength 1 */
  46     TELEPHONY_NETWORK_RSSI_2, /**< Strength 2 */
  47     TELEPHONY_NETWORK_RSSI_3, /**< Strength 3 */
  48     TELEPHONY_NETWORK_RSSI_4, /**< Strength 4 */
  49     TELEPHONY_NETWORK_RSSI_5, /**< Strength 5 */
  50     TELEPHONY_NETWORK_RSSI_6, /**< Strength 6 */
  51 } telephony_network_rssi_e;
  52
  53
  54 /**
  55  * @brief Enumeration for Network Type.
  56  * @since_tizen 2.3
  57  */
  58 typedef enum
  59 {
  60     TELEPHONY_NETWORK_TYPE_UNKNOWN, /**< Unknown */
  61     TELEPHONY_NETWORK_TYPE_GSM,     /**< 2G GSM network type */
  62     TELEPHONY_NETWORK_TYPE_GPRS,    /**< 2.5G GPRS network type */
  63     TELEPHONY_NETWORK_TYPE_EDGE,    /**< 2.5G EDGE network type */
  64     TELEPHONY_NETWORK_TYPE_UMTS,    /**< 3G UMTS network type */
  65     TELEPHONY_NETWORK_TYPE_HSDPA,   /**< HSDPA network type */
  66     TELEPHONY_NETWORK_TYPE_LTE,     /**< LTE network type */
  67 } telephony_network_type_e;
  68
  69
  70 /**
  71  * @brief Enumeration for Network Service State.
  72  * @since_tizen 2.3
  73  */
  74 typedef enum
  75 {
  76     TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE,     /**< In service */
  77     TELEPHONY_NETWORK_SERVICE_STATE_OUT_OF_SERVICE, /**< Out of service */
  78     TELEPHONY_NETWORK_SERVICE_STATE_EMERGENCY_ONLY, /**< Only emergency call is allowed */
  79 } telephony_network_service_state_e;
  80
  81 /**
  82  * @brief Gets the LAC (Location Area Code) of the current network.
  83  *
  84  * @since_tizen 2.3
  85  * @privlevel public
  86  * @privilege %http://tizen.org/privilege/telephony
  87  *
  88  * @param[in] handle The handle from telephony_init()
  89  * @param[out] lac The Location Area Code
  90  *
  91  * @return @c 0 on success,
  92  *         otherwise a negative error value
  93  *
  94  * @retval #TELEPHONY_ERROR_NONE              Successful
  95  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
  96  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
  97  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
  98  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
  99  *
 100  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 101  *
 102  * @see telephony_network_get_service_state()
 103  */
 104 int telephony_network_get_lac(telephony_h handle, int *lac);
 105
 106 /**
 107  * @brief Gets the cell ID.
 108  *
 109  * @since_tizen 2.3
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/telephony
 112  *
 113  * @param[in] handle The handle from telephony_init()
 114  * @param[out] cell_id The cell identification number
 115  *
 116  * @return @c 0 on success,
 117  *         otherwise a negative error value
 118  *
 119  * @retval #TELEPHONY_ERROR_NONE              Successful
 120  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 122  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 123  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 124  *
 125  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 126  *
 127  * @see telephony_network_get_service_state()
 128  */
 129 int telephony_network_get_cell_id(telephony_h handle, int *cell_id);
 130
 131 /**
 132  * @brief Gets the RSSI (Received Signal Strength Indicator).
 133  *
 134  * @since_tizen 2.3
 135  * @privlevel public
 136  * @privilege %%%%%http://tizen.org/privilege/telephony
 137  *
 138  * @param[in] handle The handle from telephony_init()
 139  * @param[out] rssi The Received Signal Strength Indicator \n
 140  *                  Higher the received number, the stronger the signal strength.
 141  *
 142  * @return @c 0 on success,
 143  *         otherwise a negative error value
 144  *
 145  * @retval #TELEPHONY_ERROR_NONE              Successful
 146  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 147  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 148  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 149  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 150  *
 151  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 152  *
 153  * @see telephony_network_get_service_state()
 154  */
 155 int telephony_network_get_rssi(telephony_h handle, telephony_network_rssi_e *rssi);
 156
 157 /**
 158  * @brief Gets the roaming state.
 159  *
 160  * @since_tizen 2.3
 161  * @privlevel public
 162  * @privilege %http://tizen.org/privilege/telephony
 163  *
 164  * @param[in] handle The handle from telephony_init()
 165  * @param[out] status @c true if roaming,
 166  *                    otherwise @c false if not roaming
 167  *
 168  * @return @c 0 on success,
 169  *         otherwise a negative error value
 170  *
 171  * @retval #TELEPHONY_ERROR_NONE              Successful
 172  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 173  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 174  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 175  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 176  *
 177  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 178  *
 179  * @see telephony_network_get_service_state()
 180  */
 181 int telephony_network_get_roaming_status(telephony_h handle, bool *status);
 182
 183 /**
 184  * @brief Gets the MCC (Mobile Country Code) of the current registered network.
 185  *
 186  * @since_tizen 2.3
 187  * @privlevel public
 188  * @privilege %http://tizen.org/privilege/telephony
 189  *
 190  * @remarks You must release @c mcc using free().
 191  *
 192  * @param[in] handle The handle from telephony_init()
 193  * @param[out] mcc The Mobile Country Code (three digits)
 194  *                 Mobile Country Code (MCC) identifies the country where the cell is being used.
 195  *
 196  * @return @c 0 on success,
 197  *         otherwise a negative error value
 198  *
 199  * @retval #TELEPHONY_ERROR_NONE              Successful
 200  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 201  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 202  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 203  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 204  *
 205  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 206  *
 207  * @see telephony_network_get_service_state()
 208  */
 209 int telephony_network_get_mcc(telephony_h handle, char **mcc);
 210
 211 /**
 212  * @brief Gets the MNC (Mobile Network Code) of the current registered network.
 213  *
 214  * @since_tizen 2.3
 215  * @privlevel public
 216  * @privilege %http://tizen.org/privilege/telephony
 217  *
 218  * @remarks You must release @c mnc using free().
 219  *
 220  * @param[in] handle The handle from telephony_init()
 221  * @param[out] mnc The Mobile Network Code (three digits)
 222  *                 The Mobile Network Code (MNC) identifies the mobile phone operator and network provider.
 223  *
 224  * @return @c 0 on success,
 225  *         otherwise a negative error value
 226  *
 227  * @retval #TELEPHONY_ERROR_NONE              Successful
 228  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 230  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 231  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 232  *
 233  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 234  *
 235  * @see telephony_network_get_service_state()
 236  */
 237 int telephony_network_get_mnc(telephony_h handle, char **mnc);
 238
 239 /**
 240  * @brief Gets the name of the current registered network.
 241  *
 242  * @since_tizen 2.3
 243  * @privlevel public
 244  * @privilege %http://tizen.org/privilege/telephony
 245  *
 246  * @remarks You must release @c network_name using free().
 247  *
 248  * @param[in] handle The handle from telephony_init()
 249  * @param[out] network_name The name of the current registered network
 250  *
 251  * @return @c 0 on success,
 252  *         otherwise a negative error value
 253  *
 254  * @retval #TELEPHONY_ERROR_NONE              Successful
 255  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 256  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 257  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 258  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 259  *
 260  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 261  *
 262  * @see telephony_network_get_service_state()
 263  */
 264 int telephony_network_get_network_name(telephony_h handle, char **network_name);
 265
 266 /**
 267  * @brief Gets the network service type of the current registered network.
 268  *
 269  * @since_tizen 2.3
 270  * @privlevel public
 271  * @privilege %http://tizen.org/privilege/telephony
 272  *
 273  * @param[in] handle The handle from telephony_init()
 274  * @param[out] network_type The network service type
 275  *
 276  * @return @c 0 on success,
 277  *         otherwise a negative error value
 278  *
 279  * @retval #TELEPHONY_ERROR_NONE              Successful
 280  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 281  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 282  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 283  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 284  *
 285  * @pre The Network service state must be #TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
 286  *
 287  * @see telephony_network_get_service_state()
 288  */
 289 int telephony_network_get_type(telephony_h handle,
 290     telephony_network_type_e *network_type);
 291
 292 /**
 293  * @brief Gets the current network state of the telephony service.
 294  *
 295  * @since_tizen 2.3
 296  * @privlevel public
 297  * @privilege %http://tizen.org/privilege/telephony
 298  *
 299  * @remarks To know the state of data network, refer connection API.
 300  *
 301  * @param[in] handle The handle from telephony_init()
 302  * @param[out] network_service_state The current network state
 303  *
 304  * @return @c 0 on success,
 305  *         otherwise a negative error value
 306  *
 307  * @retval #TELEPHONY_ERROR_NONE              Successful
 308  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 309  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 310  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 311  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 312  */
 313 int telephony_network_get_service_state(telephony_h handle,
 314     telephony_network_service_state_e *network_service_state);
 315
 316 /**
 317  * @}
 318  */
 319
 320 #ifdef __cplusplus
 321 }
 322 #endif
 323
 324 #endif  // __CAPI_TELEPHONY_NETWORK_INFO_H__