include/ITapiPhonebook.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2014 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Ja-young Gu <jygu@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20
  21 /**
  22  * @file ITapiPhonebook.h
  23  */
  24
  25 /**
  26  * @internal
  27  * @addtogroup CAPI_TELEPHONY_SERVICE_PHONEBOOK
  28  * @{
  29  */
  30
  31 #ifndef _ITAPI_PHONEBOOK_H_
  32 #define _ITAPI_PHONEBOOK_H_
  33
  34 #include <tapi_common.h>
  35 #include <TelSim.h>
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 /**
  43  * @brief Gets the current inserted SIM phonebook init status, available phonebook list, and first valid index in case of FDN, ADN, and 3G phonebook.
  44  *
  45  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
  46  *
  47  *          <b> Sync (or) Async: </b> This is a synchronous API. \n
  48  *
  49  *          <b> Prospective Clients: </b> External Apps. \n
  50  *
  51  * @since_tizen 2.3
  52  * @privlevel public
  53  * @privilege %http://tizen.org/privilege/telephony
  54  *
  55  * @remarks You must use phonebook-engine APIs to handle a phonebook (including SIM phonebook).
  56  *          If a user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
  57  *          The @a pb_list and @a first_index value are available when the @a init_completed status is '1' only.
  58  *
  59  * @param[in] handle The handle from tel_init()
  60  *
  61  * @param[out] init_completed The phonebook init status to use - '0' is not init, '1' is init complete
  62  *
  63  * @param[out] pb_list The available SIM phonebook list; this value is valid in the phonebook init complete case
  64  *
  65  * @return The return type (int)\n
  66  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully\n
  67  *         Negative integer - It provides an error code (Refer #TapiResult_t).
  68  */
  69 int tel_get_sim_pb_init_info(TapiHandle *handle, int *init_completed, TelSimPbList_t *pb_list);
  70
  71 /**
  72  * @brief Gets the number of used records and total records of a specific SIM phonebook type.
  73  *
  74  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
  75  *          This function makes a Dbus method call to the Telephony Server and returns an immediate value.
  76  *          However it just means that the API request has been transfered to the CP successfully.
  77  *          The actual operation result is delivered in the corresponding event asynchronously.
  78  *
  79  *          <b> Sync (or) Async: </b> This is an Asynchronous API. \n
  80  *
  81  *          <b> Prospective Clients: </b> External Apps.
  82  *
  83  * @since_tizen 2.3
  84  * @privlevel public
  85  * @privilege %http://tizen.org/privilege/telephony
  86  *
  87  * @remarks You must use phonebook-engine APIs to handle a phonebook(including SIM phonebook).
  88  *          If the user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
  89  *
  90  * @param[in] handle The handle from tel_init()
  91  *
  92  * @param[in] pb_type The different storage types to be selected in the SIM; #TelSimPbType_t
  93  *
  94  * @param[in] callback To register a callback function for result
  95  *
  96  * @param[in] user_data The user data for user specification
  97  *
  98  * @return The return type (int)\n
  99  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully\n
 100  *         Negative integer - It provides an error code (Refer #TapiResult_t).
 101  *
 102  * @pre Initialize the Dbus connection with #tel_init.
 103  */
 104 int tel_get_sim_pb_count(TapiHandle *handle, TelSimPbType_t pb_type, tapi_response_cb callback, void *user_data);
 105
 106 /**
 107  * @brief Gets the max text length and max number length supported by the SIM phone book elementary file.
 108  *
 109  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
 110  *          This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 111  *          However it just means that the API request has been transfered to the CP successfully.
 112  *          The actual operation result is being delivered in the corresponding event asynchronously.
 113  *
 114  *         <b> Sync (or) Async: </b> This is an Asynchronous API. \n
 115  *
 116  *         <b> Prospective Clients: </b> External Apps.
 117  *
 118  * @since_tizen 2.3
 119  * @privlevel public
 120  * @privilege %http://tizen.org/privilege/telephony
 121  *
 122  * @remarks The max number length includes the storage space provided by the corresponding EXT file for a given Dialling Number file.\n
 123  *          You must use phonebook-engine APIs to handle a phonebook(including SIM phonebook).
 124  *          If a user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
 125  *
 126  * @param[in] handle The handle from tel_init()
 127  *
 128  * @param[in] pb_type The different storage types to be selected in the SIM; #TelSimPbType_t
 129  *
 130  * @param[in] callback To register a callback function for result
 131  *
 132  * @param[in] user_data The user data for user specification
 133  *
 134  * @return The return type (int)\n
 135  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully \n
 136  *         Negative integer : It provides an error code (Refer #TapiResult_t).
 137  *
 138  * @pre Initialize the Dbus connection with #tel_init.
 139  */
 140 int tel_get_sim_pb_meta_info(TapiHandle *handle, TelSimPbType_t pb_type, tapi_response_cb callback, void *user_data);
 141
 142 /**
 143  * @brief Gets SIM 3G phonebook supported EFs like ANR, SNE, GRP, EMAIL and the corresponding EFs max text length, number length, and size.
 144  *
 145  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
 146  *          This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 147  *          However, it just means that the API request has been transferred to the CP successfully.
 148  *          The actual operation result is delivered in the corresponding event asynchronously.
 149  *
 150  *          <b> Sync (or) Async: </b> This is an Asynchronous API. \n
 151  *
 152  *          <b> Prospective Clients: </b> External Apps.
 153  *
 154  * @since_tizen 2.3
 155  * @privlevel public
 156  * @privilege %http://tizen.org/privilege/telephony
 157  *
 158  * @remarks You must use phonebook-engine APIs to handle a phonebook (including SIM phonebook).
 159  *          If a user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
 160  *
 161  * @param[in] handle The handle from tel_init()
 162  *
 163  * @param[in] callback To register a callback function for result
 164  *
 165  * @param[in] user_data The user data for user specification
 166  *
 167  * @return The return type (int)\n
 168  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully\n
 169  *         Negative integer : It provides an error code (Refer #TapiResult_t).
 170  *
 171  * @pre Initialize Dbus connection with #tel_init\n
 172  */
 173 int tel_get_sim_pb_usim_meta_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 174
 175 /**
 176  * @brief Reads SIM phone book entry information from the given storage type and index.
 177  *
 178  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
 179  *          This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 180  *          However it just means that the API request has been transfered to the CP successfully.
 181  *          The actual operation result is being delivered in the corresponding event asynchronously.
 182  *
 183  *          <b> Sync (or) Async: </b> This is an Asynchronous API. \n
 184  *
 185  *          <b> Prospective Clients: </b> External Apps.
 186  *
 187  * @since_tizen 2.3
 188  * @privlevel public
 189  * @privilege %http://tizen.org/privilege/telephony
 190  *
 191  * @remarks The index ranges from 1 to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.\n
 192  *          You must use phonebook-engine APIs to handle a phonebook (including SIM phonebook).
 193  *          If a user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
 194  *
 195  * @param[in] handle The handle from tel_init()
 196  *
 197  * @param[in] pb_type The different storage types to be selected in the SIM; #TelSimPbType_t
 198  *
 199  * @param[in] pb_index The index for accessing the SIM data
 200  *
 201  * @param[in] callback To register a callback function for result
 202  *
 203  * @param[in] user_data The user data for user specification
 204  *
 205  * @return The return type (int)\n
 206  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully\n
 207  *         Negative integer : It provides an error code (Refer #TapiResult_t)
 208  *
 209  * @pre Initialize the Dbus connection with #tel_init.
 210  */
 211 int tel_read_sim_pb_record(TapiHandle *handle, TelSimPbType_t pb_type, unsigned short pb_index, tapi_response_cb callback, void *user_data);
 212
 213 /**
 214  * @brief Adds or edits SIM phone book record entry information.
 215  *
 216  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
 217  *          This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 218  *          However it just means that the API request has been transfered to the CP successfully.
 219  *          The actual operation result is delivered in the corresponding event asynchronously. \n
 220  *
 221  *         <b> Sync (or) Async: </b> This is an Asynchronous API. \n
 222  *
 223  *         <b> Prospective Clients: </b> External Apps. \n
 224  *
 225  * @since_tizen 2.3
 226  * @privlevel platform
 227  * @privilege %http://tizen.org/privilege/telephony.admin
 228  *
 229  * @remarks You must use phonebook-engine APIs to handle a phonebook (including SIM phonebook).
 230  *          If a user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
 231  *
 232  * @param[in] handle The handle from tel_init()
 233  *
 234  * @param[in] req_data The phonebook data to be updated or added; #TelSimPbRecord_t
 235  *
 236  * @param[in] callback To register a callback function for result
 237  *
 238  * @param[in] user_data The user data for user specification
 239  *
 240  * @return The return type (int)\n
 241  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully\n
 242  *         Negative integer : It provides an error code (Refer #TapiResult_t).
 243  *
 244  * @pre Initialize the Dbus connection with #tel_init.
 245  */
 246 int tel_update_sim_pb_record(TapiHandle *handle, const TelSimPbRecord_t *req_data, tapi_response_cb callback, void *user_data);
 247
 248 /**
 249  * @brief Deletes a SIM phonebook record.
 250  *
 251  * @details Access to this API is limited to in-house applications and phonebook-engine APIs are recommended instead. \n
 252  *          This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 253  *          However it just means that the API request has been transfered to the CP successfully.
 254  *          The actual operation result is delivered in the corresponding event asynchronously.
 255  *
 256  *          <b> Sync (or) Async: </b> This is an Asynchronous API. \n
 257  *
 258  *          <b> Prospective Clients: </b> External Apps.
 259  *
 260  * @since_tizen 2.3
 261  * @privlevel platform
 262  * @privilege %http://tizen.org/privilege/telephony.admin
 263  *
 264  * @remarks The index ranges from 1 to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.\n
 265  *          You must use phonebook-engine APIs to handle a phonebook(including SIM phonebook).
 266  *          If the user uses SIM phonebook related APIs directly, it can break device phonebook consistency because of all the phonebook information managed in the phonebook-engine.
 267  *
 268  * @param[in] handle The handle from tel_init()
 269  *
 270  * @param[in] pb_type The different storage types to be selected in the SIM; #TelSimPbType_t
 271  *
 272  * @param[in] pb_index The index of the record to be deleted
 273  *
 274  * @param[in] callback To register a callback function for result
 275  *
 276  * @param[in] user_data The user data for user specification
 277  *
 278  * @return The return type (int)\n
 279  *         Integer '0' ( same with #TAPI_API_SUCCESS ) - indicates that the operation is completed successfully\n
 280  *         Negative integer : (It provides an error code (Refer #TapiResult_t).
 281  *
 282  * @pre Initialize the Dbus connection with #tel_init.
 283  */
 284 int tel_delete_sim_pb_record(TapiHandle *handle, TelSimPbType_t pb_type, unsigned short pb_index, tapi_response_cb callback, void *user_data);
 285
 286 #ifdef __cplusplus
 287 }
 288 #endif
 289
 290 #endif  /* _ITAPI_PHONEBOOK_H_ */
 291
 292 /**
 293 * @}
 294 */