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
  18 #ifndef __TIZEN_TELEPHONY_NETWORK_INFO_H__
  19 #define __TIZEN_TELEPHONY_NETWORK_INFO_H__
  20
  21 #include <tizen.h>
  22 #include <telephony_network_type.h>
  23
  24 #ifdef __cplusplus
  25 extern "C"
  26 {
  27 #endif
  28
  29 /**
  30  * @file network_info.h
  31  * @brief This file contains the network information APIs.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_TELEPHONY_NETWORK_INFO_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Gets the LAC ( Location Area Code ) of current network.
  41  *
  42  * @param[out] lac The Location Area Code
  43  * @return 0 on success, otherwise a negative error value.
  44  * @retval #NETWORK_INFO_ERROR_NONE Successful
  45  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
  46  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
  47  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
  48  * @pre  The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
  49  * @see network_info_get_service_state()
  50  *
  51  */
  52 int network_info_get_lac(int *lac);
  53
  54 /**
  55  * @brief Gets the cell ID.
  56  *
  57  * @param[out] cell_id The cell identification number
  58  * @return 0 on success, otherwise a negative error value.
  59  * @retval #NETWORK_INFO_ERROR_NONE Successful
  60  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
  61  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
  62  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
  63  * @pre  The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
  64  * @see network_info_get_service_state()
  65  *
  66  */
  67 int network_info_get_cell_id(int *cell_id);
  68
  69 /**
  70  * @brief Gets the RSSI (Received Signal Strength Indicator).
  71  *
  72  * @param[out] rssi The Received Signal Strength Indicator. \n
  73  * The higher the received number is, the stronger the signal strength is.
  74  *
  75  * @return 0 on success, otherwise a negative error value.
  76  * @retval #NETWORK_INFO_ERROR_NONE Successful
  77  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
  78  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
  79  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
  80  * @pre  The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
  81  * @see network_info_get_service_state()
  82  *
  83  */
  84 int network_info_get_rssi(network_info_rssi_e *rssi);
  85
  86 /**
  87  * @brief Gets the roaming state.
  88  *
  89  * @param[out] is_roaming The roaming state: (@c true = roaming, @c false = not roaming)
  90  * @return 0 on success, otherwise a negative error value.
  91  * @retval #NETWORK_INFO_ERROR_NONE Successful
  92  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
  93  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
  94  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
  95  * @pre  The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
  96  * @see network_info_get_service_state()
  97  *
  98  */
  99 int network_info_is_roaming(bool *is_roaming);
 100
 101 /**
 102  * @brief Gets the MCC (Mobile Country Code) of current network.
 103  *
 104  * @remarks @a mcc must be released with free() by you.
 105  *
 106  * @param[out] mcc The Mobile Country Code (three digits). \n
 107  * Mobile Country Code (MCC) identifies the country where the cell is being used.
 108  *
 109  * @return 0 on success, otherwise a negative error value.
 110  * @retval #NETWORK_INFO_ERROR_NONE Successful
 111  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 113  * @retval #NETWORK_INFO_ERROR_OUT_OF_MEMORY Out of memory
 114  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 115  * @pre  The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
 116  * @see network_info_get_service_state()
 117  *
 118  */
 119 int network_info_get_mcc(char **mcc);
 120
 121 /**
 122  * @brief Gets the MNC (Mobile Network Code) of current network.
 123  *
 124  * @remarks @a mnc must be released with free() by you.
 125  *
 126  * @param[out] mnc The Mobile Network Code (three digits). \n
 127  * The Mobile Network Code (MNC) identifies the mobile phone operator and network provider.
 128  *
 129  * @return 0 on success, otherwise a negative error value.
 130  * @retval #NETWORK_INFO_ERROR_NONE Successful
 131  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 132  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 133  * @retval #NETWORK_INFO_ERROR_OUT_OF_MEMORY Out of memory
 134  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 135  * @pre The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
 136  * @see network_info_get_service_state()
 137  *
 138  */
 139 int network_info_get_mnc(char **mnc);
 140
 141 /**
 142  * @brief Gets the name of the network provider.
 143  *
 144  * @remarks @a provider_name must be released with free() by you.
 145  *
 146  * @param[out] provider_name The name of the network provider
 147  * @return 0 on success, otherwise a negative error value.
 148  * @retval #NETWORK_INFO_ERROR_NONE Successful
 149  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 150  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 151  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 152  * @pre The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
 153  * @see network_info_get_service_state()
 154  *
 155  */
 156 int network_info_get_provider_name(char **provider_name);
 157
 158 /**
 159  * @brief Gets the network type.
 160  *
 161  * @param[out] network_type The network type of telephony
 162  *
 163  * @return 0 on success, otherwise a negative error value.
 164  * @retval #NETWORK_INFO_ERROR_NONE Successful
 165  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 167  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 168  * @pre The Network service state must be #NETWORK_INFO_SERVICE_STATE_IN_SERVICE.
 169  * @see network_info_get_service_state()
 170  *
 171  */
 172 int network_info_get_type(network_info_type_e *network_type);
 173
 174 /**
 175  * @brief Gets the network state of the telephony service.
 176  *
 177  * @remarks To know the state of data network, call connection_get_network_status() in Connection Service.
 178  * @param[out] network_service_state The network state of call service
 179  * @return 0 on success, otherwise a negative error value.
 180  * @retval #NETWORK_INFO_ERROR_NONE Successful
 181  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 182  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 183  *
 184  */
 185 int network_info_get_service_state(network_info_service_state_e *network_service_state);
 186
 187 /**
 188  * @brief  Called when the cell ID changes.
 189  * @remarks If the cell ID changes, then LAC, MCC, MNC, provider name and network type can be changed.
 190  * @param [in] cell_id The cell identification number to be changed
 191  * @param [in] user_data The user data passed from the callback registration function
 192  * @pre This callback function is invoked if you register this function using network_info_set_cell_id_changed_cb().
 193  * @see network_info_set_cell_id_changed_cb()
 194  * @see network_info_unset_cell_id_changed_cb()
 195  */
 196 typedef void(* network_info_cell_id_changed_cb)(int cell_id, void *user_data);
 197
 198 /**
 199  * @brief Registers a callback function to be invoked when the cell ID changes.
 200  *
 201  * @param [in] callback The callback function to register
 202  * @param [in] user_data The user data to be passed to the callback function
 203  * @return 0 on success, otherwise a negative error value.
 204  * @retval #NETWORK_INFO_ERROR_NONE Successful
 205  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 207  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 208  * @post network_info_cell_id_changed_cb() will be invoked.
 209  * @see network_info_cell_id_changed_cb()
 210  * @see network_info_unset_cell_id_changed_cb()
 211  *
 212  */
 213 int network_info_set_cell_id_changed_cb(network_info_cell_id_changed_cb callback, void *user_data);
 214
 215 /**
 216  * @brief Unregisters the callback function.
 217  *
 218  * @return 0 on success, otherwise a negative error value.
 219  * @retval #NETWORK_INFO_ERROR_NONE Successful
 220  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Operation failed
 221  * @see network_info_cell_id_changed_cb()
 222  * @see network_info_set_cell_id_changed_cb()
 223  *
 224  */
 225 int network_info_unset_cell_id_changed_cb();
 226
 227 /**
 228  * @brief Invoked when the RSSI (Received Signal Strength Indicator) changes.
 229  * @param [in] rssi The Received Signal Strength Indicator
 230  * @param [in] user_data The user data passed from the callback registration function
 231  * @pre This callback function is invoked if you register this function using network_info_set_rssi_changed_cb().
 232  * @see network_info_set_rssi_changed_cb()
 233  * @see network_info_unset_rssi_changed_cb()
 234  */
 235 typedef void(* network_info_rssi_changed_cb)(network_info_rssi_e rssi, void *user_data);
 236
 237 /**
 238  * @brief Registers a callback function to be invoked when RSSI (Received Signal Strength Indicator) changes.
 239  *
 240  * @param [in] callback The callback function to register
 241  * @param [in] user_data The user data to be passed to the callback function
 242  * @return 0 on success, otherwise a negative error value.
 243  * @retval #NETWORK_INFO_ERROR_NONE Successful
 244  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 246  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 247  * @post network_info_rssi_changed_cb() will be invoked.
 248  * @see network_info_rssi_changed_cb()
 249  * @see network_info_unset_rssi_changed_cb()
 250  *
 251  */
 252 int network_info_set_rssi_changed_cb(network_info_rssi_changed_cb callback, void *user_data);
 253
 254 /**
 255  * @brief Unregisters the callback function.
 256  *
 257  * @return 0 on success, otherwise a negative error value.
 258  * @retval #NETWORK_INFO_ERROR_NONE Successful
 259  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Operation failed
 260  * @see network_info_rssi_changed_cb()
 261  * @see network_info_set_rssi_changed_cb()
 262  *
 263  */
 264 int network_info_unset_rssi_changed_cb();
 265
 266 /**
 267  * @brief Invoked when the roaming state changes.
 268  * @param [in] is_roaming The roaming state
 269  * @param [in] user_data The user data passed from the callback registration function
 270  * @pre This callback function is invoked if you register this function using network_info_set_roaming_state_changed_cb().
 271  * @see network_info_set_roaming_state_changed_cb()
 272  * @see network_info_unset_roaming_state_changed_cb()
 273  */
 274 typedef void(* network_info_roaming_state_changed_cb)(bool is_roaming, void *user_data);
 275
 276 /**
 277  * @brief Registers a callback function to be invoked when roaming state changes.
 278  *
 279  * @param [in] callback The callback function to register
 280  * @param [in] user_data The user data to be passed to the callback function
 281  * @return 0 on success, otherwise a negative error value.
 282  * @retval #NETWORK_INFO_ERROR_NONE Successful
 283  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 284  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 285  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 286  * @post network_info_roaming_state_changed_cb() will be invoked.
 287  * @see network_info_roaming_state_changed_cb()
 288  * @see network_info_unset_roaming_state_changed_cb()
 289  *
 290  */
 291 int network_info_set_roaming_state_changed_cb(network_info_roaming_state_changed_cb callback, void *user_data);
 292
 293 /**
 294  * @brief Unregisters the callback function.
 295  *
 296  * @return 0 on success, otherwise a negative error value.
 297  * @retval #NETWORK_INFO_ERROR_NONE Successful
 298  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Operation failed
 299  * @see network_info_roaming_state_changed_cb()
 300  * @see network_info_set_roaming_changed_cb()
 301  *
 302  */
 303 int network_info_unset_roaming_state_changed_cb();
 304
 305 /**
 306  * @brief Invoked when the state of the telephony service changes.
 307  * @param [in] network_service_state The state of telephony service
 308  * @param [in] user_data The user data passed from the callback registration function
 309  * @pre This callback function is invoked if you register this function using network_info_set_service_state_changed_cb().
 310  * @see #network_info_service_state_e
 311  * @see network_info_set_service_state_changed_cb()
 312  * @see  network_info_unset_service_state_changed_cb()
 313  */
 314 typedef void(* network_info_service_state_changed_cb)(network_info_service_state_e network_service_state, void *user_data);
 315
 316 /**
 317  * @brief Registers a callback function to be invoked when telephony service state changes.
 318  *
 319  * @param [in] callback The callback function to register
 320  * @param [in] user_data The user data to be passed to the callback function
 321  * @return 0 on success, otherwise a negative error value.
 322  * @retval #NETWORK_INFO_ERROR_NONE Successful
 323  * @retval #NETWORK_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 324  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Internal error
 325  * @retval #NETWORK_INFO_ERROR_OUT_OF_SERVICE Out of service
 326  * @post network_info_service_state_changed_cb() will be invoked.
 327  * @see network_info_unset_service_state_changed_cb()
 328  */
 329 int network_info_set_service_state_changed_cb(network_info_service_state_changed_cb callback, void *user_data);
 330
 331 /**
 332  * @brief Unregisters the callback function.
 333  *
 334  * @return 0 on success, otherwise a negative error value.
 335  * @retval #NETWORK_INFO_ERROR_NONE Successful
 336  * @retval #NETWORK_INFO_ERROR_OPERATION_FAILED Operation failed
 337  * @see network_info_service_state_changed_cb()
 338  * @see network_info_set_service_state_changed_cb()
 339  */
 340 int network_info_unset_service_state_changed_cb();
 341
 342
 343 /**
 344  * @}
 345  */
 346
 347
 348 #ifdef __cplusplus
 349 }
 350 #endif
 351
 352 #endif  // __TIZEN_TELEPHONY_NETWORK_INFO_H__