include/telephony_common.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_COMMON_H__
  18 #define __CAPI_TELEPHONY_COMMON_H__
  19
  20 /**
  21  * @file telephony_common.h
  22  * @brief This file contains telephony common APIs and related enumerations.
  23  */
  24
  25 #include <tizen.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @file telephony_common.h
  33  * @brief This file contains the common information APIs.
  34  */
  35
  36 /**
  37  * @addtogroup CAPI_TELEPHONY_INFORMATION
  38  * @{
  39  */
  40
  41 /**
  42  * @brief The Telephony API handle.
  43  * @since_tizen 2.3
  44  */
  45 typedef struct telephony_data *telephony_h;
  46
  47 /**
  48  * @brief The structure type for the list of handles to use the Telephony API.
  49  * @remarks There are two handles in case of dual SIM device. \n
  50  *          In this case, handle[0] is mean Primary SIM and handle[1] is mean Secondary SIM.
  51  * @since_tizen 2.3
  52  */
  53 typedef struct {
  54     unsigned int count; /**< Number of available handle */
  55     telephony_h *handle; /**< Handle to use Telephony API */
  56 } telephony_handle_list_s;
  57
  58 /**
  59  * @brief Enumeration for Telephony error.
  60  * @since_tizen 2.3
  61  */
  62 typedef enum {
  63     TELEPHONY_ERROR_NONE = TIZEN_ERROR_NONE,                            /**< Successful */
  64     TELEPHONY_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,          /**< Out of memory */
  65     TELEPHONY_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  66     TELEPHONY_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,  /**< Permission denied */
  67     TELEPHONY_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,          /**< Not supported */
  68     TELEPHONY_ERROR_OPERATION_FAILED = TIZEN_ERROR_TELEPHONY | 0x0001,  /**< Operation failed */
  69     TELEPHONY_ERROR_SIM_NOT_AVAILABLE = TIZEN_ERROR_TELEPHONY | 0x1001, /**< SIM is not available */
  70 } telephony_error_e;
  71
  72 /**
  73  * @brief Enumeration for Telephony notification.
  74  * @since_tizen 2.3
  75  */
  76 typedef enum  {
  77     TELEPHONY_NOTI_SIM_STATUS = 0x10,            /**< Notification to be invoked when the SIM card state changes */
  78
  79     TELEPHONY_NOTI_NETWORK_SERVICE_STATE = 0x20, /**< Notification to be invoked when the network service state changes */
  80     TELEPHONY_NOTI_NETWORK_CELLID,               /**< Notification to be invoked when the cell ID changes */
  81     TELEPHONY_NOTI_NETWORK_ROAMING_STATUS,       /**< Notification to be invoked when the roaming status changes */
  82     TELEPHONY_NOTI_NETWORK_SIGNALSTRENGTH_LEVEL, /**< Notification to be invoked when the signal strength changes */
  83
  84     TELEPHONY_NOTI_VOICE_CALL_STATE = 0x30,      /**< Notification to be invoked when the voice call state changes */
  85     TELEPHONY_NOTI_VIDEO_CALL_STATE              /**< Notification to be invoked when the video call state changes */
  86 } telephony_noti_e;
  87
  88 /**
  89  * @brief Called when the telephony state changes.
  90  * @since_tizen 2.3
  91  */
  92 typedef void (*telephony_noti_cb)(telephony_h handle, telephony_noti_e noti_id, void *data, void *user_data);
  93
  94 /**
  95  * @brief Sets a callback function to be invoked when the telephony state changes.
  96  *
  97  * @since_tizen 2.3
  98  * @privlevel public
  99  * @privilege %http://tizen.org/privilege/telephony
 100  *
 101  * @param[in] handle  The handle to use the telephony API
 102  * @param[in] noti_id The notification ID to set the callback
 103  * @param[in] cb The callback to be invoked when the telephony state changes
 104  * @param[in] user_data The user data passed to the callback function
 105  *
 106  * @return @c 0 on success,
 107  *         otherwise a negative error value
 108  *
 109  * @retval #TELEPHONY_ERROR_NONE              Successful
 110  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 111  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 112  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 113  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 114  *
 115  * @post telephony_noti_cb() will be invoked.
 116  *
 117  * @see telephony_unset_noti_cb()
 118  */
 119 int telephony_set_noti_cb(telephony_h handle,
 120     telephony_noti_e noti_id, telephony_noti_cb cb, void *user_data);
 121
 122 /**
 123  * @brief Unsets a callback function.
 124  *
 125  * @since_tizen 2.3
 126  * @privlevel public
 127  * @privilege %http://tizen.org/privilege/telephony
 128  *
 129  * @param[in] handle  The handle to use the telephony API
 130  * @param[in] noti_id The notification ID to unset a callback
 131  *
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  *
 135  * @retval #TELEPHONY_ERROR_NONE              Successful
 136  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 138  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 139  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 140  *
 141  * @see telephony_set_noti_cb()
 142  */
 143 int telephony_unset_noti_cb(telephony_h handle, telephony_noti_e noti_id);
 144
 145 /**
 146  * @brief Acquires the list of available handles to use the telephony API.
 147  *
 148  * @since_tizen 2.3
 149  *
 150  * @remarks You will get two handles in case of dual SIM device. \n
 151  *          In this case, handle[0] is mean Primary SIM and handle[1] is mean Secondary SIM.
 152  *
 153  * @param[out] list The list contains the number of
 154  *                  available handles and array of handles
 155  *
 156  * @return @c 0 on success,
 157  *         otherwise a negative error value
 158  *
 159  * @retval #TELEPHONY_ERROR_NONE              Successful
 160  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 162  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 163  *
 164  * @see telephony_deinit()
 165  */
 166 int telephony_init(telephony_handle_list_s *list);
 167
 168 /**
 169  * @brief Deinitializes the telephony handle list.
 170  *
 171  * @since_tizen 2.3
 172  *
 173  * @param[in] list The handle list to be deinitialized
 174  *
 175  * @return @c 0 on success,
 176  *         otherwise a negative error value
 177  *
 178  * @retval #TELEPHONY_ERROR_NONE              Successful
 179  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 181  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 182  *
 183  * @see telephony_init()
 184  */
 185 int telephony_deinit(telephony_handle_list_s *list);
 186
 187 /**
 188  * @}
 189  */
 190
 191 #ifdef __cplusplus
 192 }
 193 #endif
 194
 195 #endif /* __CAPI_TELEPHONY_COMMON_H__ */