include/net_connection.h

   1 /*
   2  * Copyright (c) 2011-2013 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_NETWORK_NET_CONNECTION_H__
  19 #define __TIZEN_NETWORK_NET_CONNECTION_H__
  20
  21
  22 #include <connection_profile.h>
  23
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29
  30 /**
  31  * @file net_connection.h
  32  */
  33
  34
  35 /**
  36  * @addtogroup CAPI_NETWORK_CONNECTION_MANAGER_MODULE
  37  * @{
  38  */
  39
  40
  41 /**
  42  * @brief The connection handle.
  43  * @since_tizen 2.3
  44 */
  45 typedef void* connection_h;
  46
  47
  48 /**
  49  * @brief The profiles iterator handle.
  50  * @since_tizen 2.3
  51 */
  52 typedef void* connection_profile_iterator_h;
  53
  54
  55 /**
  56  * @brief Enumeration for connection type.
  57  * @since_tizen 2.3
  58  */
  59 typedef enum {
  60         CONNECTION_TYPE_DISCONNECTED = 0,  /**< Disconnected */
  61         CONNECTION_TYPE_WIFI = 1,          /**< Wi-Fi type */
  62         CONNECTION_TYPE_CELLULAR = 2,      /**< Cellular type */
  63         CONNECTION_TYPE_ETHERNET = 3,      /**< Ethernet type */
  64         CONNECTION_TYPE_BT = 4,            /**< Bluetooth type */
  65         CONNECTION_TYPE_NET_PROXY,         /**< Proxy type for Internet connection (Since 3.0) */
  66 } connection_type_e;
  67
  68
  69 /**
  70  * @brief Enumeration for cellular network state.
  71  * @since_tizen 2.3
  72  */
  73 typedef enum {
  74         CONNECTION_CELLULAR_STATE_OUT_OF_SERVICE = 0,      /**< Out of service */
  75         CONNECTION_CELLULAR_STATE_FLIGHT_MODE = 1,         /**< Flight mode */
  76         CONNECTION_CELLULAR_STATE_ROAMING_OFF = 2,         /**< Roaming is turned off */
  77         CONNECTION_CELLULAR_STATE_CALL_ONLY_AVAILABLE = 3, /**< Call is only available */
  78         CONNECTION_CELLULAR_STATE_AVAILABLE = 4,           /**< Available but not connected yet */
  79         CONNECTION_CELLULAR_STATE_CONNECTED = 5,           /**< Connected */
  80 } connection_cellular_state_e;
  81
  82
  83 /**
  84  * @brief Enumeration for Wi-Fi state.
  85  * @since_tizen 2.3
  86  */
  87 typedef enum {
  88         CONNECTION_WIFI_STATE_DEACTIVATED = 0,   /**< Wi-Fi is deactivated */
  89         CONNECTION_WIFI_STATE_DISCONNECTED = 1,  /**< Disconnected */
  90         CONNECTION_WIFI_STATE_CONNECTED = 2,     /**< Connected */
  91 } connection_wifi_state_e;
  92
  93
  94 /**
  95  * @brief Enumeration for ethernet state.
  96  * @since_tizen 2.4
  97  */
  98 typedef enum {
  99         CONNECTION_ETHERNET_STATE_DEACTIVATED = 0,  /**< There is no Ethernet profile to open */
 100         CONNECTION_ETHERNET_STATE_DISCONNECTED = 1, /**< Disconnected */
 101         CONNECTION_ETHERNET_STATE_CONNECTED = 2,    /**< Connected */
 102 } connection_ethernet_state_e;
 103
 104
 105 /**
 106  * @brief Enumeration for Bluetooth state.
 107  * @since_tizen 2.3
 108  */
 109 typedef enum {
 110         CONNECTION_BT_STATE_DEACTIVATED = 0,   /**< There is no Bluetooth profile to open */
 111         CONNECTION_BT_STATE_DISCONNECTED = 1,  /**< Disconnected */
 112         CONNECTION_BT_STATE_CONNECTED = 2,     /**< Connected */
 113 } connection_bt_state_e;
 114
 115
 116 /**
 117  * @brief Enumeration for connection iterator type.
 118  * @since_tizen 2.3
 119  */
 120 typedef enum {
 121         CONNECTION_ITERATOR_TYPE_REGISTERED = 0, /**< The iterator of the registered profile */
 122         CONNECTION_ITERATOR_TYPE_CONNECTED = 1,  /**< The iterator of the connected profile */
 123         CONNECTION_ITERATOR_TYPE_DEFAULT = 2,    /**< The iterator of the default profile */
 124 } connection_iterator_type_e;
 125
 126
 127 /**
 128  * @brief Enumeration for reset profile type.
 129  * @since_tizen 2.3
 130 */
 131 typedef enum {
 132         /**
 133          * Initialized with the default profile defined by csc
 134          */
 135         CONNECTION_RESET_DEFAULT_PROFILE = 0,
 136
 137         /**
 138          * Remove all profiles
 139          */
 140         CONNECTION_RESET_CLEAR_PROFILE = 1,
 141
 142 } connection_reset_option_e;
 143
 144
 145 /**
 146  * @brief Enumeration for the attached or detached state of ethernet cable.
 147  * @since_tizen 2.4
 148  */
 149 typedef enum {
 150         CONNECTION_ETHERNET_CABLE_DETACHED = 0,   /**< Ethernet cable is detached */
 151         CONNECTION_ETHERNET_CABLE_ATTACHED = 1,   /**< Ethernet cable is attached */
 152 } connection_ethernet_cable_state_e;
 153
 154 /**
 155  * @brief Enumeration for the DHCP state.
 156  * @since_tizen 8.0
 157  */
 158 typedef enum {
 159         CONNECTION_DHCP_STATE_UNKNOWN = 0,  /**< Unknown state */
 160         CONNECTION_DHCP_STATE_STARTED = 1,  /**< DHCP is running */
 161         CONNECTION_DHCP_STATE_FINISHED = 2, /**< DHCP is finished */
 162 } connection_dhcp_state_e;
 163
 164 /**
 165  * @brief Enumeration for connection errors.
 166  * @since_tizen 2.3
 167  */
 168 typedef enum {
 169         /**
 170          * Successful
 171          */
 172         CONNECTION_ERROR_NONE = TIZEN_ERROR_NONE,
 173
 174         /**
 175          * Invalid parameter
 176          */
 177         CONNECTION_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,
 178
 179         /**
 180          * Out of memory error
 181          */
 182         CONNECTION_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,
 183
 184         /**
 185          * Invalid operation
 186          */
 187         CONNECTION_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,
 188
 189         /**
 190          * Address family not supported
 191          */
 192         CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED = TIZEN_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED,
 193
 194         /**
 195          * Now inprogress
 196          */
 197         CONNECTION_ERROR_NOW_IN_PROGRESS = TIZEN_ERROR_NOW_IN_PROGRESS,
 198
 199         /**
 200          * Permission denied
 201          */
 202         CONNECTION_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,
 203
 204         /**
 205          * Not supported
 206          */
 207         CONNECTION_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,
 208
 209         /**
 210          * Operation failed
 211          */
 212         CONNECTION_ERROR_OPERATION_FAILED = TIZEN_ERROR_CONNECTION|0x0401,
 213
 214         /**
 215          * End of iteration
 216          */
 217         CONNECTION_ERROR_ITERATOR_END = TIZEN_ERROR_CONNECTION|0x0402,
 218
 219         /**
 220          * There is no connection
 221          */
 222         CONNECTION_ERROR_NO_CONNECTION = TIZEN_ERROR_CONNECTION|0x0403,
 223
 224         /**
 225          * Already exists
 226          */
 227         CONNECTION_ERROR_ALREADY_EXISTS = TIZEN_ERROR_CONNECTION|0x0404,
 228
 229         /**
 230          * Operation is aborted
 231          */
 232         CONNECTION_ERROR_OPERATION_ABORTED = TIZEN_ERROR_CONNECTION|0x0405,
 233
 234         /**
 235          * DHCP failed
 236          */
 237         CONNECTION_ERROR_DHCP_FAILED = TIZEN_ERROR_CONNECTION|0x0406,
 238
 239         /**
 240          * Invalid key
 241          */
 242         CONNECTION_ERROR_INVALID_KEY = TIZEN_ERROR_CONNECTION|0x0407,
 243
 244         /**
 245          * No reply
 246          */
 247         CONNECTION_ERROR_NO_REPLY = TIZEN_ERROR_CONNECTION|0x0408,
 248
 249         /**
 250          * Already initialized (Since 5.0)
 251          */
 252         CONNECTION_ERROR_ALREADY_INITIALIZED = TIZEN_ERROR_CONNECTION|0x0409,
 253
 254         /**
 255          * Not initialized (Since 5.0)
 256          */
 257         CONNECTION_ERROR_NOT_INITIALIZED = TIZEN_ERROR_CONNECTION|0x040A,
 258
 259 } connection_error_e;
 260
 261 /**
 262  * @}
 263 */
 264
 265
 266 /**
 267  * @addtogroup CAPI_NETWORK_CONNECTION_STATISTICS_MODULE
 268  * @{
 269 */
 270
 271
 272 /**
 273  * @brief Enumeration for statistics type.
 274  * @since_tizen 2.3
 275  */
 276 typedef enum {
 277         CONNECTION_STATISTICS_TYPE_LAST_RECEIVED_DATA = 0,  /**< Last received data */
 278         CONNECTION_STATISTICS_TYPE_LAST_SENT_DATA = 1,      /**< Last sent data */
 279         CONNECTION_STATISTICS_TYPE_TOTAL_RECEIVED_DATA = 2, /**< Total received data */
 280         CONNECTION_STATISTICS_TYPE_TOTAL_SENT_DATA = 3,     /**< Total sent data */
 281 } connection_statistics_type_e;
 282
 283
 284 /**
 285  * @}
 286 */
 287
 288
 289 /**
 290  * @addtogroup CAPI_NETWORK_CONNECTION_MANAGER_MODULE
 291  * @{
 292 */
 293
 294
 295 /**
 296  * @brief Creates a handle for managing data connections.
 297  * @details If you do not use this function and use other functions,
 298  *          you will get the #CONNECTION_ERROR_NOT_INITIALIZED error.
 299  *          If you put an invalid handle, you will get the #CONNECTION_ERROR_INVALID_PARAMETER error.
 300  * @since_tizen 2.3
 301  * @privlevel public
 302  * @privilege %http://tizen.org/privilege/network.get
 303  * @remarks You must release @a connection using connection_destroy().
 304  * @param[out] connection       The connection handle
 305  * @return @c 0 on success,
 306  *         otherwise a negative error value
 307  * @retval #CONNECTION_ERROR_NONE                  Successful
 308  * @retval #CONNECTION_ERROR_ALREADY_INITIALIZED   Already initialized
 309  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 310  * @retval #CONNECTION_ERROR_OUT_OF_MEMORY         Out of memory
 311  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 312  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 313  * @see connection_destroy()
 314  */
 315 int connection_create(connection_h* connection);
 316
 317
 318 /**
 319  * @brief Destroys the connection handle.
 320  * @since_tizen 2.3
 321  * @param[in] connection        The connection handle
 322  * @return @c 0 on success,
 323  *         otherwise a negative error value
 324  * @retval #CONNECTION_ERROR_NONE                  Successful
 325  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 326  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 327  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 328  * @see connection_create()
 329  */
 330 int connection_destroy(connection_h connection);
 331
 332
 333 /**
 334  * @brief Called when the type of a connection is changed.
 335  * @since_tizen 2.3
 336  * @param[in] type              The type of the current network connection
 337  * @param[in] user_data         The user data passed from the callback registration function
 338  * @see connection_set_type_changed_cb()
 339  * @see connection_unset_type_changed_cb()
 340  */
 341 typedef void(*connection_type_changed_cb)(connection_type_e type, void* user_data);
 342
 343
 344 /**
 345  * @brief Called when the address is changed.
 346  * @since_tizen 2.3
 347  * @remarks @a ipv4_address @a ipv6_address should not be freed.
 348  *          @a ipv4_address @a ipv6_address is available only in the callback.
 349  *          To use outside the callback, make a copy.
 350  * @param[in] ipv4_address      The IP address for IPv4
 351  * @param[in] ipv6_address      The IP address for IPv6
 352  * @param[in] user_data         The user data passed from the callback registration function
 353  * @see connection_set_ip_address_changed_cb()
 354  * @see connection_unset_ip_address_changed_cb()
 355  * @see connection_set_proxy_address_changed_cb()
 356  * @see connection_unset_proxy_address_changed_cb()
 357  */
 358 typedef void(*connection_address_changed_cb)(const char* ipv4_address,
 359                 const char* ipv6_address, void* user_data);
 360
 361
 362 /**
 363  * @brief Called when connection_set_default_cellular_service_profile_async() finishes.
 364  * @since_tizen 2.3
 365  * @param[in] result            The result
 366  * @param[in] user_data         The user data passed from connection_open_profile()
 367  * @pre connection_set_default_cellular_service_profile_async() will invoke this callback function.
 368  * @see connection_set_default_cellular_service_profile_async()
 369 */
 370 typedef void(*connection_set_default_cb)(connection_error_e result, void* user_data);
 371
 372 /**
 373  * @brief Called with an IPv6 address.
 374  * @since_tizen 4.0
 375  * @remarks   If @a ipv6_address is needed outside the callback, a copy should be made. \n
 376  *            @a ipv6_address will be freed automatically after the execution of this callback.
 377  * @param[in]  ipv6_address     The IPv6 address
 378  * @param[in]  user_data        The user data passed from the foreach function
 379  * @return  @c true to continue with the next iteration of the loop, \n
 380  *          @c false to break out of the loop
 381  * @pre  connection_foreach_ipv6_address() will invoke this callback.
 382  * @see  connection_foreach_ipv6_address()
 383  */
 384 typedef bool(*connection_ipv6_address_cb)(char *ipv6_address, void *user_data);
 385
 386 /**
 387  * @brief Called when the DHCP state is changed.
 388  * @since_tizen 8.0
 389  * @param[in]  state            The DHCP state
 390  * @param[in]  interface_name   The interface name with DHCP state change
 391  * @param[in]  result           The result of DHCP operation
 392  * @param[in]  user_data        The user data passed from the callback registration function
 393  * @see  connection_set_dhcp_state_changed_cb()
 394  * @see  connection_unset_dhcp_state_changed_cb()
 395  */
 396 typedef void(*connection_dhcp_state_changed_cb)(connection_dhcp_state_e state,
 397             const char *interface_name, connection_error_e result, void *user_data);
 398
 399 /**
 400  * @brief Gets the type of the current profile for data connection.
 401  * @since_tizen 2.3
 402  * @param[in] connection        The connection handle
 403  * @param[out] type             The type of the network
 404  * @return @c 0 on success,
 405  *         otherwise a negative error value
 406  * @retval #CONNECTION_ERROR_NONE                  Successful
 407  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 408  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 409  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 410  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 411  */
 412 int connection_get_type(connection_h connection, connection_type_e* type);
 413
 414
 415 /**
 416  * @brief Gets the IP address of the current connection.
 417  * @since_tizen 2.3
 418  * @remarks You must release @a ip_address using free().
 419  * @param[in] connection        The connection handle
 420  * @param[in] address_family    The address family
 421  * @param[out] ip_address       The pointer to the IP address string
 422  * @return @c 0 on success,
 423  *         otherwise a negative error value
 424  * @retval #CONNECTION_ERROR_NONE                           Successful
 425  * @retval #CONNECTION_ERROR_NOT_INITIALIZED                Not initialized
 426  * @retval #CONNECTION_ERROR_INVALID_PARAMETER              Invalid parameter
 427  * @retval #CONNECTION_ERROR_OPERATION_FAILED               Operation failed
 428  * @retval #CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED   Not supported address family
 429  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 430  */
 431 int connection_get_ip_address(connection_h connection,
 432                 connection_address_family_e address_family, char** ip_address);
 433
 434
 435 /**
 436  * @brief Gets the proxy address of the current connection.
 437  * @since_tizen 2.3
 438  * @remarks You must release @a proxy using free().
 439  * @param[in] connection        The connection handle
 440  * @param[in] address_family    The address family
 441  * @param[out] proxy            The proxy address
 442  * @return @c 0 on success,
 443  *         otherwise a negative error value
 444  * @retval #CONNECTION_ERROR_NONE                           Successful
 445  * @retval #CONNECTION_ERROR_NOT_INITIALIZED                Not initialized
 446  * @retval #CONNECTION_ERROR_INVALID_PARAMETER              Invalid parameter
 447  * @retval #CONNECTION_ERROR_OPERATION_FAILED               Operation failed
 448  * @retval #CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED   Not supported address family
 449  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 450  */
 451 int connection_get_proxy(connection_h connection,
 452                 connection_address_family_e address_family, char** proxy);
 453
 454
 455 /**
 456  * @brief Gets the MAC address of the Wi-Fi or ethernet.
 457  * @since_tizen 2.4
 458  * @remarks @a mac_addr must be released with free() by you.
 459  * @param[in] connection        The handle of the connection
 460  * @param[in] type              The type of current network connection
 461  * @param[out] mac_addr         The MAC address
 462  * @return @c 0 on success,
 463  *         otherwise a negative error value
 464  * @retval #CONNECTION_ERROR_NONE                  Successful
 465  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 466  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 467  * @retval #CONNECTION_ERROR_INVALID_OPERATION     Invalid operation
 468  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 469  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 470  * @retval #CONNECTION_ERROR_OUT_OF_MEMORY         Out of memory
 471  */
 472 int connection_get_mac_address(connection_h connection,
 473                 connection_type_e type, char** mac_addr);
 474
 475
 476 /**
 477  * @brief Gets if the current connection is metered.
 478  * @since_tizen 4.0
 479  * @privlevel public
 480  * @privilege %http://tizen.org/privilege/network.get
 481  * @param[in] connection        The connection handle
 482  * @param[out] is_metered       The value indicating whether it is metered
 483  * @return @c 0 on success,
 484  *         otherwise a negative error value
 485  * @retval #CONNECTION_ERROR_NONE                  Successful
 486  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 487  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 488  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 489  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 490  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 491  */
 492 int connection_is_metered_network(connection_h connection, bool* is_metered);
 493
 494
 495 /**
 496  * @brief Gets the state of cellular connection.
 497  * @details The returned state is for the cellular connection state.
 498  * @since_tizen 2.3
 499  * @param[in] connection        The connection handle
 500  * @param[out] state            The state of the cellular connection
 501  * @return @c 0 on success,
 502  *         otherwise a negative error value
 503  * @retval #CONNECTION_ERROR_NONE                  Successful
 504  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 505  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 506  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 507  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 508  */
 509 int connection_get_cellular_state(connection_h connection, connection_cellular_state_e* state);
 510
 511
 512 /**
 513  * @brief Gets the state of the Wi-Fi.
 514  * @details The returned state is for the Wi-Fi connection state.
 515  * @since_tizen 2.3
 516  * @privlevel public
 517  * @privilege %http://tizen.org/privilege/network.get
 518  * @param[in] connection        The connection handle
 519  * @param[out] state            The state of Wi-Fi connection
 520  * @return @c 0 on success,
 521  *         otherwise a negative error value
 522  * @retval #CONNECTION_ERROR_NONE                  Successful
 523  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 524  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 525  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 526  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 527  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 528  */
 529 int connection_get_wifi_state(connection_h connection, connection_wifi_state_e* state);
 530
 531
 532 /**
 533  * @brief Gets the state of the Ethernet.
 534  * @details The returned state is for the Ethernet connection state.
 535  * @since_tizen 2.4
 536  * @privlevel public
 537  * @privilege %http://tizen.org/privilege/network.get
 538  * @param[in] connection        The connection handle
 539  * @param[out] state            The state of Ethernet connection
 540  * @return @c 0 on success,
 541  *         otherwise a negative error value
 542  * @retval #CONNECTION_ERROR_NONE                  Successful
 543  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 544  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 545  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 546  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 547  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 548  */
 549 int connection_get_ethernet_state(connection_h connection, connection_ethernet_state_e* state);
 550
 551
 552 /**
 553  * @brief Called when the Internet state of the current connection is changed.
 554  * @since_tizen 5.5
 555  * @param[in] state             The Internet state of current connection
 556  * @param[in] user_data         The user data passed to callback registration function
 557  */
 558 typedef void(*connection_internet_state_changed_cb)(
 559                 connection_internet_state_e state, void* user_data);
 560
 561 /**
 562  * @brief Sets the callback that is called when the Internet availability over the current connection is changed.
 563  * @since_tizen 5.5
 564  * @param[in] connection        The connection handle
 565  * @param[in] callback          The callback function to be called
 566  * @param[in] user_data         The user data passed to the callback function
 567  * @return @c 0 on success,
 568  *         otherwise a negative error value
 569  * @retval #CONNECTION_ERROR_NONE                  Successful
 570  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 571  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 572  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 573  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 574  */
 575 int connection_set_internet_state_changed_cb(connection_h connection,
 576                 connection_internet_state_changed_cb callback, void *user_data);
 577
 578
 579 /**
 580  * @brief Unsets the callback that is called when the Internet state of the current connection is changed.
 581  * @since_tizen 5.5
 582  * @param[in] connection        The connection handle
 583  * @return @c 0 on success,
 584  *         otherwise a negative error value
 585  * @retval #CONNECTION_ERROR_NONE                  Successful
 586  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 587  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 588  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 589  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 590  */
 591 int connection_unset_internet_state_changed_cb(connection_h connection);
 592
 593 /**
 594  * @brief Checks for ethernet cable is attached or not.
 595  * @details The returned state is for the ethernet cable state.
 596  * @since_tizen 2.4
 597  * @privlevel public
 598  * @privilege %http://tizen.org/privilege/network.get
 599  * @param[in] connection        The handle of the connection
 600  * @param[in] state             The state of ethernet cable
 601  * @return @c 0 on success,
 602  *         otherwise a negative error value
 603  * @retval #CONNECTION_ERROR_NONE                  Successful
 604  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 605  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 606  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 607  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 608  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 609  */
 610 int connection_get_ethernet_cable_state(connection_h connection,
 611                 connection_ethernet_cable_state_e *state);
 612
 613
 614 /**
 615  * @brief Gets the DHCP state of the interface.
 616  * @since_tizen 8.0
 617  * @privlevel public
 618  * @privilege %http://tizen.org/privilege/network.get
 619  * @param[in] connection        The connection handle
 620  * @param[in] interface_name    The interface name
 621  * @param[out] state            The DHCP state of the interface
 622  * @return @c 0 on success,
 623  *         otherwise a negative error value
 624  * @retval #CONNECTION_ERROR_NONE                  Successful
 625  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 626  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 627  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 628  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 629  */
 630 int connection_get_dhcp_state(connection_h connection,
 631                 const char *interface_name, connection_dhcp_state_e *state);
 632
 633
 634 /**
 635  * @deprecated Deprecated since 4.0. Use connection_ethernet_cable_state_changed_cb() instead.
 636  * @brief Called when ethernet cable is plugged [in/out].
 637  * @since_tizen 2.4
 638  * @param[in] state             The state of ethernet cable
 639  * @param[in] user_data         The user data passed to callback registration function
 640  */
 641 typedef void(*connection_ethernet_cable_state_chaged_cb)
 642                 (connection_ethernet_cable_state_e state, void* user_data);
 643
 644
 645 /**
 646  * @deprecated Deprecated since 4.0. Use connection_set_ethernet_cable_state_changed_cb() instead.
 647  * @brief Sets callback for ethernet cable is plugged [in/out] event.
 648  * @since_tizen 2.4
 649  * @param[in] connection        The connection handle
 650  * @param[in] callback          The callback function to be called
 651  * @param[in] user_data         The user data passed to the callback function
 652  * @return @c 0 on success,
 653  *         otherwise a negative error value
 654  * @retval #CONNECTION_ERROR_NONE                  Successful
 655  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 656  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 657  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 658  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 659  */
 660 int connection_set_ethernet_cable_state_chaged_cb(connection_h connection,
 661                 connection_ethernet_cable_state_chaged_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 662
 663
 664 /**
 665  * @deprecated Deprecated since 4.0. Use connection_unset_ethernet_cable_state_changed_cb() instead.
 666  * @brief Unsets callback for ethernet cable is plugged [in/out] event.
 667  * @since_tizen 2.4
 668  * @param[in] connection        The connection handle
 669  * @return @c 0 on success,
 670  *         otherwise a negative error value
 671  * @retval #CONNECTION_ERROR_NONE                  Successful
 672  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 673  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 674  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 675  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 676  */
 677 int connection_unset_ethernet_cable_state_chaged_cb(connection_h connection) TIZEN_DEPRECATED_API;
 678
 679 /**
 680  * @brief Called when ethernet cable is plugged [in/out].
 681  * @since_tizen 4.0
 682  * @param[in] state             The state of ethernet cable
 683  * @param[in] user_data         The user data passed to callback registration function
 684  */
 685 typedef void(*connection_ethernet_cable_state_changed_cb)(
 686                 connection_ethernet_cable_state_e state, void* user_data);
 687
 688
 689 /**
 690  * @brief Sets callback for ethernet cable is plugged [in/out] event.
 691  * @since_tizen 4.0
 692  * @param[in] connection        The connection handle
 693  * @param[in] callback          The callback function to be called
 694  * @param[in] user_data         The user data passed to the callback function
 695  * @return @c 0 on success,
 696  *         otherwise a negative error value
 697  * @retval #CONNECTION_ERROR_NONE                  Successful
 698  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 699  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 700  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 701  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 702  */
 703 int connection_set_ethernet_cable_state_changed_cb(connection_h connection,
 704                 connection_ethernet_cable_state_changed_cb callback, void *user_data);
 705
 706
 707 /**
 708  * @brief Unsets callback for ethernet cable is plugged [in/out] event.
 709  * @since_tizen 4.0
 710  * @param[in] connection        The connection handle
 711  * @return @c 0 on success,
 712  *         otherwise a negative error value
 713  * @retval #CONNECTION_ERROR_NONE                  Successful
 714  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 715  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 716  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 717  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 718  */
 719 int connection_unset_ethernet_cable_state_changed_cb(connection_h connection);
 720
 721
 722 /**
 723  * @brief Gets the state of the Bluetooth.
 724  * @details The returned state is for the Bluetooth connection state.
 725  * @since_tizen 2.3
 726  * @privlevel public
 727  * @privilege %http://tizen.org/privilege/network.get
 728  * @param[in] connection        The connection handle
 729  * @param[out] state            The state of the Bluetooth connection
 730  * @return @c 0 on success,
 731  *         otherwise a negative error value
 732  * @retval #CONNECTION_ERROR_NONE                  Successful
 733  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 734  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 735  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 736  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 737  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 738  */
 739 int connection_get_bt_state(connection_h connection, connection_bt_state_e* state);
 740
 741
 742 /**
 743  * @brief Sets the callback that is called when the type of the current connection is changed.
 744  * @since_tizen 2.3
 745  * @param[in] connection        The connection handle
 746  * @param[in] callback          The callback function to be called
 747  * @param[in] user_data         The user data passed to the callback function
 748  * @return @c 0 on success,
 749  *         otherwise a negative error value
 750  * @retval #CONNECTION_ERROR_NONE                  Successful
 751  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 752  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 753  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 754  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 755  */
 756 int connection_set_type_changed_cb(connection_h connection,
 757                 connection_type_changed_cb callback, void* user_data);
 758
 759
 760 /**
 761  * @brief Unsets the callback that is called when the type of current connection is changed.
 762  * @since_tizen 2.3
 763  * @param[in] connection        The connection handle
 764  * @return @c 0 on success,
 765  *         otherwise a negative error value
 766  * @retval #CONNECTION_ERROR_NONE                  Successful
 767  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 768  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 769  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 770  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 771  */
 772 int connection_unset_type_changed_cb(connection_h connection);
 773
 774
 775 /**
 776  * @brief Sets the callback that is called when the IP address is changed.
 777  * @since_tizen 2.3
 778  * @param[in] connection        The connection handle
 779  * @param[in] callback          The callback function to be called
 780  * @param[in] user_data         The user data passed to the callback function
 781  * @return @c 0 on success,
 782  *         otherwise a negative error value
 783  * @retval #CONNECTION_ERROR_NONE                  Successful
 784  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 785  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 786  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 787  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 788  */
 789 int connection_set_ip_address_changed_cb(connection_h connection,
 790                 connection_address_changed_cb callback, void* user_data);
 791
 792
 793 /**
 794  * @brief Unsets the callback that is called when the IP address is changed.
 795  * @since_tizen 2.3
 796  * @param[in] connection        The connection handle
 797  * @return @c 0 on success,
 798  *         otherwise a negative error value
 799  * @retval #CONNECTION_ERROR_NONE                  Successful
 800  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 801  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 802  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 803  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 804  */
 805 int connection_unset_ip_address_changed_cb(connection_h connection);
 806
 807
 808 /**
 809  * @brief Sets the callback that is called when the proxy address is changed.
 810  * @since_tizen 2.3
 811  * @param[in] connection        The connection handle
 812  * @param[in] callback          The callback function to be called
 813  * @param[in] user_data         The user data passed to the callback function
 814  * @return @c 0 on success,
 815  *         otherwise a negative error value
 816  * @retval #CONNECTION_ERROR_NONE                  Successful
 817  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 818  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 819  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 820  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 821  */
 822 int connection_set_proxy_address_changed_cb(connection_h connection,
 823                 connection_address_changed_cb callback, void* user_data);
 824
 825
 826 /**
 827  * @brief Unsets the callback that is called when the proxy address is changed.
 828  * @since_tizen 2.3
 829  * @param[in] connection        The connection handle
 830  * @return @c 0 on success,
 831  *         otherwise a negative error value
 832  * @retval #CONNECTION_ERROR_NONE                  Successful
 833  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 834  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 835  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 836  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 837  */
 838 int connection_unset_proxy_address_changed_cb(connection_h connection);
 839
 840
 841 /**
 842  * @brief Sets the callback that is called when the DHCP state is changed.
 843  * @since_tizen 8.0
 844  * @param[in] connection        The connection handle
 845  * @param[in] callback          The callback function to be called
 846  * @param[in] user_data         The user data passed to the callback function
 847  * @return @c 0 on success,
 848  *         otherwise a negative error value
 849  * @retval #CONNECTION_ERROR_NONE                  Successful
 850  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 851  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 852  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 853  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 854  */
 855 int connection_set_dhcp_state_changed_cb(connection_h connection,
 856                 connection_dhcp_state_changed_cb callback, void *user_data);
 857
 858
 859 /**
 860  * @brief Unsets the callback that is called when the DHCP state is changed.
 861  * @since_tizen 8.0
 862  * @param[in] connection        The connection handle
 863  * @return @c 0 on success,
 864  *         otherwise a negative error value
 865  * @retval #CONNECTION_ERROR_NONE                  Successful
 866  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 867  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 868  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 869  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 870  */
 871 int connection_unset_dhcp_state_changed_cb(connection_h connection);
 872
 873
 874 /**
 875  * @brief Adds a new profile which is created by connection_profile_create().
 876  * @since_tizen 2.3
 877  * @privlevel public
 878  * @privilege %http://tizen.org/privilege/network.profile
 879  * @remarks You can only add a profile of the cellular type.
 880  * @param[in] connection        The connection handle
 881  * @param[in] profile           The profile handle
 882  * @return @c 0 on success,
 883  *         otherwise a negative error value
 884  * @retval #CONNECTION_ERROR_NONE                  Successful
 885  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 886  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 887  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 888  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 889  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 890  */
 891 int connection_add_profile(connection_h connection, connection_profile_h profile);
 892
 893
 894 /**
 895  * @brief Removes an existing profile.
 896  * @since_tizen 2.3
 897  * @privlevel public
 898  * @privilege %http://tizen.org/privilege/network.profile \n
 899  *            %http://tizen.org/privilege/network.get
 900  * @remarks This function needs both privileges.
 901  * @param[in] connection        The connection handle
 902  * @param[in] profile           The profile handle
 903  * @return @c 0 on success,
 904  *         otherwise a negative error value
 905  * @retval #CONNECTION_ERROR_NONE                  Successful
 906  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 907  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 908  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 909  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 910  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 911  */
 912 int connection_remove_profile(connection_h connection, connection_profile_h profile);
 913
 914
 915 /**
 916  * @brief Updates an existing profile.
 917  * @details When a profile is changed, these changes will be not applied to the
 918  *          Connection Manager immediately.
 919  *          When you call this function, your changes affect the Connection Manager
 920  *          and the existing profile is updated.
 921  *          In addition, the existing profile will be updated if you call connection_open_profile().
 922  * @since_tizen 2.3
 923  * @privlevel public
 924  * @privilege %http://tizen.org/privilege/network.profile \n
 925  *            %http://tizen.org/privilege/network.get
 926  * @remarks This function needs both privileges.
 927  * @param[in] connection        The connection handle
 928  * @param[in] profile           The profile handle
 929  * @return @c 0 on success,
 930  *         otherwise a negative error value
 931  * @retval #CONNECTION_ERROR_NONE                  Successful
 932  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 933  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 934  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 935  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 936  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 937  * @see connection_open_profile()
 938  */
 939 int connection_update_profile(connection_h connection, connection_profile_h profile);
 940
 941
 942 /**
 943  * @brief Gets a profiles iterator.
 944  * @since_tizen 2.3
 945  * @privlevel public
 946  * @privilege %http://tizen.org/privilege/network.get
 947  * @remarks You must release @a profile_iterator using connection_destroy().
 948  * @param[in] connection        The connection handle
 949  * @param[in] type              The type of the connection iterator
 950  * @param[out] profile_iterator The iterator of profile
 951  * @return @c 0 on success,
 952  *         otherwise a negative error value
 953  * @retval #CONNECTION_ERROR_NONE                  Successful
 954  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 955  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 956  * @retval #CONNECTION_ERROR_OUT_OF_MEMORY         Out of memory
 957  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
 958  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
 959  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 960  */
 961 int connection_get_profile_iterator(connection_h connection,
 962                 connection_iterator_type_e type, connection_profile_iterator_h* profile_iterator);
 963
 964
 965 /**
 966  * @brief Moves the profile iterator to the next position and gets a profile handle.
 967  * @since_tizen 2.3
 968  * @param[in] profile_iterator  The iterator of profile
 969  * @param[out] profile          The profile handle
 970  * @return @c 0 on success,
 971  *         otherwise a negative error value
 972  * @retval #CONNECTION_ERROR_NONE                  Successful
 973  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
 974  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
 975  * @retval #CONNECTION_ERROR_ITERATOR_END          End of iteration
 976  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 977  */
 978 int connection_profile_iterator_next(connection_profile_iterator_h profile_iterator,
 979                 connection_profile_h* profile);
 980
 981
 982 /**
 983  * @brief Checks whether the next element of a profile iterator exists or not.
 984  * @since_tizen 2.3
 985  * @remarks The specific error code can be obtained using the get_last_result() method.
 986  *          Error codes are described in Exception section.
 987  * @param[in] profile_iterator  The iterator of profile
 988  * @return @c true if next element exists,
 989  *         otherwise @c false if next element doesn't exist
 990  * @exception #CONNECTION_ERROR_NONE                  Successful
 991  * @retval #CONNECTION_ERROR_NOT_INITIALIZED          Not initialized
 992  * @exception #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
 993  * @see get_last_result()
 994  */
 995 bool connection_profile_iterator_has_next(connection_profile_iterator_h profile_iterator);
 996
 997
 998 /**
 999  * @brief Destroys a profiles iterator.
1000  * @since_tizen 2.3
1001  * @param[in] profile_iterator  The iterator of the profile
1002  * @return @c 0 on success,
1003  *         otherwise a negative error value
1004  * @retval #CONNECTION_ERROR_NONE                  Successful
1005  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1006  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1007  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1008  */
1009 int connection_destroy_profile_iterator(connection_profile_iterator_h profile_iterator);
1010
1011
1012 /**
1013  * @brief Gets the name of the default profile.
1014  * @since_tizen 2.3
1015  * @privlevel public
1016  * @privilege %http://tizen.org/privilege/network.get
1017  * @remarks You must release @a profile using connection_profile_destroy().
1018  * @param[in] connection        The connection handle
1019  * @param[out] profile          The profile handle
1020  * @return @c 0 on success,
1021  *         otherwise a negative error value
1022  * @retval #CONNECTION_ERROR_NONE                  Successful
1023  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1024  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1025  * @retval #CONNECTION_ERROR_OUT_OF_MEMORY         Out of memory
1026  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1027  * @retval #CONNECTION_ERROR_NO_CONNECTION         There is no connection
1028  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1029  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1030  */
1031 int connection_get_current_profile(connection_h connection, connection_profile_h* profile);
1032
1033
1034 /**
1035  * @brief Gets the default profile which provides the given cellular service.
1036  * @since_tizen 2.3
1037  * @privlevel public
1038  * @privilege %http://tizen.org/privilege/network.get
1039  * @remarks You must release @a profile using connection_profile_destroy().
1040  * @param[in] connection        The connection handle
1041  * @param[in] type              The type of cellular service \n
1042  *            #CONNECTION_CELLULAR_SERVICE_TYPE_APPLICATION is not permitted
1043  * @param[out] profile          The profile handle
1044  * @return @c 0 on success,
1045  *         otherwise a negative error value
1046  * @retval #CONNECTION_ERROR_NONE                  Successful
1047  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1048  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1049  * @retval #CONNECTION_ERROR_OUT_OF_MEMORY         Out of memory
1050  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1051  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1052  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1053  */
1054 int connection_get_default_cellular_service_profile(connection_h connection,
1055                 connection_cellular_service_type_e type, connection_profile_h* profile);
1056
1057
1058 /**
1059  * @brief Sets the default profile which provides the given cellular service.
1060  * @since_tizen 2.3
1061  * @privlevel public
1062  * @privilege %http://tizen.org/privilege/network.profile \n
1063  *            %http://tizen.org/privilege/network.get
1064  * @remarks This function needs both privileges.
1065  * @param[in] connection        The connection handle
1066  * @param[in] type              The type of cellular service \n
1067  *            Only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and
1068  *            #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are permitted
1069  * @param[in] profile           The profile handle
1070  * @return @c 0 on success,
1071  *         otherwise a negative error value
1072  * @retval #CONNECTION_ERROR_NONE                  Successful
1073  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1074  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1075  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1076  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1077  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1078  */
1079 int connection_set_default_cellular_service_profile(connection_h connection,
1080                 connection_cellular_service_type_e type, connection_profile_h profile);
1081
1082
1083 /**
1084  * @brief Sets the default profile which provides the given cellular service, asynchronously.
1085  * @since_tizen 2.3
1086  * @privlevel public
1087  * @privilege %http://tizen.org/privilege/network.profile \n
1088  *                %http://tizen.org/privilege/network.get
1089  * @remarks This function needs both privileges.
1090  * @param[in] connection        The connection handle
1091  * @param[in] type              The type of cellular service \n
1092  *            Only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and
1093  *            #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are permitted
1094  * @param[in] profile The profile handle
1095  * @param[in] callback The callback function to be called
1096  * @param[in] user_data The user data passed to the callback function
1097  * @return @c 0 on success,
1098  *         otherwise a negative error value
1099  * @retval #CONNECTION_ERROR_NONE                  Successful
1100  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1101  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1102  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1103  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1104  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1105  */
1106 int connection_set_default_cellular_service_profile_async(connection_h connection,
1107                 connection_cellular_service_type_e type, connection_profile_h profile,
1108                 connection_set_default_cb callback, void* user_data);
1109
1110
1111 /**
1112  * @brief Called after connection_open_profile() is finished.
1113  * @since_tizen 2.3
1114  * @param[in] result            The result
1115  * @param[in] user_data         The user data passed from connection_open_profile()
1116  * @pre connection_open_profile() will invoke this callback function.
1117  * @see connection_open_profile()
1118 */
1119 typedef void(*connection_opened_cb)(connection_error_e result, void* user_data);
1120
1121
1122 /**
1123  * @brief Called after connection_close_profile() is finished.
1124  * @since_tizen 2.3
1125  * @param[in] result            The result
1126  * @param[in] user_data         The user data passed from connection_close_profile()
1127  * @pre connection_close_profile() will invoke this callback function.
1128  * @see connection_close_profile()
1129 */
1130 typedef void(*connection_closed_cb)(connection_error_e result, void* user_data);
1131
1132
1133 /**
1134  * @brief Called after connection_reset_profile() is finished.
1135  * @since_tizen 2.3
1136  * @param[in] result            The result
1137  * @param[in] user_data         The user data passed from connection_reset_profile()
1138  * @pre connection_reset_profile() will invoke this callback function.
1139  * @see connection_reset_profile()
1140 */
1141 typedef void(*connection_reset_cb)(connection_error_e result, void* user_data);
1142
1143
1144 /**
1145  * @brief Opens a connection of profile, asynchronously.
1146  * @since_tizen 2.3
1147  * @privlevel public
1148  * @privilege %http://tizen.org/privilege/network.set \n
1149  *            %http://tizen.org/privilege/network.get
1150  * @remarks This function needs both privileges.
1151  * @param[in] connection        The connection handle
1152  * @param[in] profile           The profile handle
1153  * @param[in] callback          The callback function to be called
1154  * @param[in] user_data         The user data passed to the callback function
1155  * @return @c 0 on success,
1156  *         otherwise a negative error value
1157  * @retval #CONNECTION_ERROR_NONE                  Successful
1158  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1159  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1160  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1161  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1162  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1163  * @post connection_opened_cb() will be invoked.
1164  * @see connection_opened_cb()
1165  * @see connection_close_profile()
1166  * @see connection_profile_set_state_changed_cb()
1167  * @see connection_profile_unset_state_changed_cb()
1168  * @see connection_profile_state_changed_cb()
1169  */
1170 int connection_open_profile(connection_h connection, connection_profile_h profile,
1171                 connection_opened_cb callback, void* user_data);
1172
1173
1174 /**
1175  * @brief Closes a connection of profile.
1176  * @since_tizen 2.3
1177  * @privlevel public
1178  * @privilege %http://tizen.org/privilege/network.set
1179  * @param[in] connection        The connection handle
1180  * @param[in] profile           The profile handle
1181  * @param[in] callback          The callback function to be called
1182  * @param[in] user_data         The user data passed to the callback function
1183  * @return @c 0 on success,
1184  *         otherwise a negative error value
1185  * @retval #CONNECTION_ERROR_NONE                  Successful
1186  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1187  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1188  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1189  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1190  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1191  * @post connection_closed_cb() will be invoked.
1192  * @see connection_closed_cb()
1193  * @see connection_open_profile()
1194  * @see connection_profile_set_state_changed_cb()
1195  * @see connection_profile_unset_state_changed_cb()
1196  * @see connection_profile_state_changed_cb()
1197  */
1198 int connection_close_profile(connection_h connection, connection_profile_h profile,
1199                 connection_closed_cb callback, void* user_data);
1200
1201
1202 /**
1203  * @brief Resets the cellular profile.
1204  * @since_tizen 2.3
1205  * @privlevel public
1206  * @privilege %http://tizen.org/privilege/network.profile \n
1207  *                %http://tizen.org/privilege/network.get
1208  * @remarks This function needs both privileges.
1209  * @param[in] connection        The connection handle
1210  * @param[in] type              The type of reset
1211  * @param[in] id                The subscriber identity module ID to reset
1212  *                              (The sim index starts from 0.)
1213  * @param[in] callback          The callback function to be called
1214  * @param[in] user_data         The user data passed to the callback function
1215  * @return @c 0 on success,
1216  *         otherwise a negative error value
1217  * @retval #CONNECTION_ERROR_NONE                  Successful
1218  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1219  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1220  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1221  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1222  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1223  * @post connection_reset_cb() will be invoked.
1224 */
1225 int connection_reset_profile(connection_h connection, connection_reset_option_e type,
1226                 int id, connection_reset_cb callback, void *user_data);
1227
1228
1229 /**
1230  * @platform
1231  * @deprecated Deprecated since 4.0. Use connection_add_route_entry() instead.
1232  * @brief Adds a IPv4 route to the routing table.
1233  * @details You can get the @a interface_name from
1234  *          connection_profile_get_network_interface_name() of opened profile.
1235  * @since_tizen 2.3
1236  * @privlevel partner
1237  * @privilege %http://tizen.org/privilege/network.route
1238  * @remarks Since 6.0, the required privilege and level of this function has changed.
1239  * @param[in] connection        The connection handle
1240  * @param[in] interface_name    The name of network interface
1241  * @param[in] host_address      The IP address of the host
1242  * @return @c 0 on success,
1243  *         otherwise a negative error value
1244  * @retval #CONNECTION_ERROR_NONE                  Successful
1245  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1246  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1247  * @retval #CONNECTION_ERROR_ALREADY_EXISTS        Already exists
1248  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1249  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1250  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1251  * @see connection_profile_get_network_interface_name()
1252  */
1253 int connection_add_route(connection_h connection, const char* interface_name,
1254                 const char* host_address) TIZEN_DEPRECATED_API;
1255
1256
1257 /**
1258  * @platform
1259  * @deprecated Deprecated since 4.0. Use connection_remove_route_entry() instead.
1260  * @brief Removes a IPv4 route from the routing table.
1261  * @details You can get the @a interface_name from
1262  *          connection_profile_get_network_interface_name() of opened profile.
1263  * @since_tizen 2.3
1264  * @privlevel partner
1265  * @privilege %http://tizen.org/privilege/network.route
1266  * @remarks Since 6.0, the required privilege and level of this function has changed.
1267  * @param[in] connection        The connection handle
1268  * @param[in] interface_name    The name of network interface
1269  * @param[in] host_address      The IP address of the host
1270  * @return @c 0 on success,
1271  *         otherwise a negative error value
1272  * @retval #CONNECTION_ERROR_NONE                  Successful
1273  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1274  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1275  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1276  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1277  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1278  * @see connection_profile_get_network_interface_name()
1279  */
1280 int connection_remove_route(connection_h connection, const char* interface_name,
1281                 const char* host_address) TIZEN_DEPRECATED_API;
1282
1283
1284 /**
1285  * @platform
1286  * @deprecated Deprecated since 4.0. Use connection_add_route_entry() instead.
1287  * @brief Adds a IPv6 route to the routing table.
1288  * @details You can get the @a interface_name from
1289  *          connection_profile_get_network_interface_name() of opened profile.
1290  * @since_tizen 2.3.1
1291  * @privlevel partner
1292  * @privilege %http://tizen.org/privilege/network.route
1293  * @remarks Since 6.0, the required privilege and level of this function has changed.
1294  * @param[in] connection        The connection handle
1295  * @param[in] interface_name    The name of network interface
1296  * @param[in] host_address      The IP address of the host
1297  * @param[in] gateway           The gateway address
1298  * @return @c 0 on success,
1299  *         otherwise a negative error value
1300  * @retval #CONNECTION_ERROR_NONE                  Successful
1301  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1302  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1303  * @retval #CONNECTION_ERROR_ALREADY_EXISTS        Already exists
1304  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1305  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1306  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1307  * @see connection_profile_get_network_interface_name()
1308  */
1309 int connection_add_route_ipv6(connection_h connection, const char *interface_name,
1310                 const char *host_address, const char * gateway) TIZEN_DEPRECATED_API;
1311
1312
1313 /**
1314  * @platform
1315  * @deprecated Deprecated since 4.0. Use connection_remove_route_entry() instead.
1316  * @brief Removes a IPV6 route from the routing table.
1317  * @details You can get the @a interface_name from
1318  *          connection_profile_get_network_interface_name() of opened profile.
1319  * @since_tizen 2.3.1
1320  * @privlevel partner
1321  * @privilege %http://tizen.org/privilege/network.route
1322  * @remarks Since 6.0, the required privilege and level of this function has changed.
1323  * @param[in] connection        The connection handle
1324  * @param[in] interface_name    The name of network interface
1325  * @param[in] host_address      The IP address of the host
1326  * @param[in] gateway           The gateway address
1327  * @return @c 0 on success,
1328  *         otherwise a negative error value
1329  * @retval #CONNECTION_ERROR_NONE                  Successful
1330  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1331  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1332  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1333  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1334  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1335  * @see connection_profile_get_network_interface_name()
1336  */
1337 int connection_remove_route_ipv6(connection_h connection, const char *interface_name,
1338                 const char *host_address, const char * gateway) TIZEN_DEPRECATED_API;
1339
1340 /**
1341  * @platform
1342  * @brief Adds a route to the routing table.
1343  * @details You can get the @a interface_name from \n
1344  *          connection_profile_get_network_interface_name() of opened profile.
1345  * @since_tizen 4.0
1346  * @privlevel partner
1347  * @privilege %http://tizen.org/privilege/network.route
1348  * @remarks Since 6.0, the required privilege and level of this function has changed.
1349  * @param[in] connection        The connection handle
1350  * @param[in] address_family    The address family
1351  * @param[in] interface_name    The name of network interface
1352  * @param[in] host_address      The IP address of the host (e.g., single IP address such as
1353  *            163.152.10.2,192.168.1.2), group's IP address (e.g., 163.152.10.0, 192.168.0.0)
1354  *            is not allowed
1355  * @param[in] gateway           The gateway address
1356  * @return @c 0 on success,
1357  *         otherwise a negative error value
1358  * @retval #CONNECTION_ERROR_NONE                  Successful
1359  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1360  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1361  * @retval #CONNECTION_ERROR_ALREADY_EXISTS        Already exists
1362  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1363  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1364  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1365  * @see connection_profile_get_network_interface_name()
1366  */
1367 int connection_add_route_entry(connection_h connection,
1368                 connection_address_family_e address_family, const char *interface_name,
1369                 const char *host_address, const char *gateway);
1370
1371 /**
1372  * @platform
1373  * @brief Removes a route from the routing table.
1374  * @details You can get the @a interface_name from \n
1375  *          connection_profile_get_network_interface_name() of opened profile.
1376  * @since_tizen 4.0
1377  * @privlevel partner
1378  * @privilege %http://tizen.org/privilege/network.route
1379  * @remarks Since 6.0, the required privilege and level of this function has changed.
1380  * @param[in] connection        The connection handle
1381  * @param[in] address_family    The address family
1382  * @param[in] interface_name    The name of network interface
1383  * @param[in] host_address      The IP address of the host (e.g., single IP address such as
1384  *            163.152.10.2,192.168.1.2), group's IP address (e.g., 163.152.10.0, 192.168.0.0)
1385  *            is not allowed
1386  * @param[in] gateway           The gateway address
1387  * @return @c 0 on success,
1388  *         otherwise a negative error value
1389  * @retval #CONNECTION_ERROR_NONE                  Successful
1390  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1391  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1392  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1393  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1394  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1395  * @see connection_profile_get_network_interface_name()
1396  */
1397 int connection_remove_route_entry(connection_h connection,
1398                 connection_address_family_e address_family, const char *interface_name,
1399                 const char *host_address, const char *gateway);
1400
1401 /**
1402  * @brief Gets all IPv6 addresses assigned to the network interface.
1403  * @since_tizen 4.0
1404  * @param[in] connection       The connection handle
1405  * @param[in] connection_type  The connection type
1406  * @param[in] callback         The callback to be called for each IPv6 address
1407  * @param[in] user_data        The user data passed to the callback function
1408  * @return 0 on success, otherwise negative error value.
1409  * @retval #CONNECTION_ERROR_NONE               Successful
1410  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1411  * @retval #CONNECTION_ERROR_INVALID_PARAMETER  Invalid parameter
1412  * @retval #CONNECTION_ERROR_OPERATION_FAILED   Operation failed
1413  * @retval #CONNECTION_ERROR_NOT_SUPPORTED      Not supported
1414  */
1415 int connection_foreach_ipv6_address(connection_h connection, connection_type_e connection_type,
1416                 connection_ipv6_address_cb callback, void *user_data);
1417
1418 /**
1419  * @}
1420 */
1421
1422
1423 /**
1424  * @addtogroup CAPI_NETWORK_CONNECTION_STATISTICS_MODULE
1425  * @{
1426 */
1427
1428
1429 /**
1430  * @brief Gets the statistics information.
1431  * @since_tizen 2.3
1432  * @privlevel public
1433  * @privilege %http://tizen.org/privilege/network.get
1434  * @param[in] connection The connection handle
1435  * @param[in] connection_type   The type of connection \n
1436  *            Only #CONNECTION_TYPE_WIFI and #CONNECTION_TYPE_CELLULAR are supported
1437  * @param[in] statistics_type   The type of statistics
1438  * @param[out] size             The received data size of the last cellular packet data connection (bytes)
1439  * @return @c 0 on success,
1440  *         otherwise a negative error value
1441  * @retval #CONNECTION_ERROR_NONE                  Successful
1442  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1443  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1444  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1445  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1446  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1447  */
1448 int connection_get_statistics(connection_h connection, connection_type_e connection_type,
1449                 connection_statistics_type_e statistics_type, long long* size);
1450
1451
1452 /**
1453  * @brief Resets the statistics information.
1454  * @since_tizen 2.3
1455  * @privlevel public
1456  * @privilege %http://tizen.org/privilege/network.set
1457  * @param[in] connection        The connection handle
1458  * @param[in] connection_type   The type of connection \n
1459  *            Only #CONNECTION_TYPE_WIFI and #CONNECTION_TYPE_CELLULAR are supported
1460  * @param[in] statistics_type   The type of statistics
1461  * @return @c 0 on success,
1462  *         otherwise a negative error value
1463  * @retval #CONNECTION_ERROR_NONE                  Successful
1464  * @retval #CONNECTION_ERROR_NOT_INITIALIZED       Not initialized
1465  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
1466  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
1467  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
1468  * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
1469  */
1470 int connection_reset_statistics(connection_h connection, connection_type_e connection_type,
1471                 connection_statistics_type_e statistics_type);
1472 /**
1473  * @}
1474 */
1475
1476
1477 #ifdef __cplusplus
1478 }
1479 #endif /* __cplusplus */
1480
1481
1482 #endif /* __TIZEN_NETWORK_NET_CONNECTION_H__ */