include/ITapiPhonebook.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2012 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 * @open
  23 * @ingroup              TelephonyAPI
  24 * @addtogroup   PHONEBOOK_TAPI  PHONEBOOK
  25 * @{
  26 *
  27 * @file ITapiPhonebook.h
  28
  29      @brief This file serves as a "C" header file defines functions for Tapi SIM phonebook Services.\n
  30       It contains a sample set of function prototypes that would be required by applications.
  31
  32 */
  33
  34 #ifndef _ITAPI_PHONEBOOK_H_
  35 #define _ITAPI_PHONEBOOK_H_
  36
  37 #include <tapi_common.h>
  38 #include <TelErr.h>
  39 #include <TelSim.h>
  40 #include <TelDefines.h>
  41
  42 #ifdef __cplusplus
  43 extern "C"
  44 {
  45 #endif
  46
  47 /**
  48  * @brief  This function is used to get current inserted SIM phonebook init status, available phonebook list and first valid index in case of FDN, ADN, 3G phonebook.
  49  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
  50  *
  51  * @par Sync (or) Async:
  52  * This is an synchronous API.
  53  *
  54  * @par Important Notes:
  55  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
  56  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
  57  * pb_list and first_index value are available at init_completed status is '1' only.
  58  *
  59  * @warning
  60  * - None.
  61  *
  62  * @param [in] handle
  63  * - handle from tel_init().
  64  *
  65  * @param [out] init_completed
  66  *   - phonebook init status. '0' is not init, '1' is init complete to use.
  67  *
  68  * @param [out] pb_list
  69  *   - available SIM phonebook list. This value is valid in phonebook init complete case.
  70  *
  71  * @par Async Response Message:
  72  * - None.
  73  *
  74  * @pre
  75  *  - None.
  76  *
  77  * @post
  78  *  - None.
  79  *
  80  * @return Return Type (int) \n
  81  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
  82  * - Negative integer : it provides an error code (Refer #TapiResult_t)
  83  *
  84  * @par Prospective Clients:
  85  * External Apps.
  86  *
  87  * @see None
  88  *
  89  * @code
  90  * #include <ITapiSim.h>
  91  * int err_code = 0;
  92  * int valid_index = 0; // usim or sim adn first valid index
  93  * TelSimPbList_t pb_list = {0,};
  94  * int pPbInitCompleted = 0; // init or not
  95  *
  96  * // GET SIM PHONEBOOK INIT INFORMATION
  97  * err_code = tel_get_sim_pb_init_info(&pPbInitCompleted, &pb_list, &valid_index);
  98  * @endcode
  99  *
 100  * @remarks None
 101  *
 102  */
 103 /*================================================================================================*/
 104 int tel_get_sim_pb_init_info(TapiHandle *handle, int *init_completed, TelSimPbList_t *pb_list);
 105
 106
 107 /**
 108  * @brief  This API is used to get number of used records and total records in specific SIM phonebook type.
 109  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 110  *
 111  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 112  * However it just means that the API request has been transfered to the CP successfully.
 113  * The actual operation result is being delivered in the corresponding event asynchronously.
 114  *
 115  * @par Sync (or) Async:
 116  * This is an Asynchronous API.
 117  *
 118  * @par Important Notes:
 119  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 120  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 121  *
 122  * @warning
 123  * - None.
 124  *
 125  *
 126  * @param [in] handle
 127  * - handle from tel_init().
 128  *
 129  * @param[in] pb_type
 130  * -Different storage types to be selected in SIM. #TelSimPbType_t
 131  *
 132  * @param [in] callback
 133  * - To register callback function for result.
 134  *
 135  * @param [in] user_data
 136  * - user_data for user specification.
 137  *
 138  * @par Async Response Message:
 139  * The event associated is TAPI_EVENT_SIM_PB_STORAGE_COUNT_CNF  and the event data is #TelSimPbStorageInfo_t.
 140  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 141  *
 142  * @pre
 143  *  - A dbus connection is established with #tel_init
 144  *  - The application name is registered with #tel_register_app_name
 145  *  - The application is registered events to listen asynchronous response with #tel_register_event
 146  *  - A event loop is running to listen events
 147  *
 148  * @post
 149  *  - None.
 150  *
 151  * @return Return Type (int) \n
 152  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 153  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 154  *
 155  * @par Prospective Clients:
 156  * External Apps.
 157  *
 158  * @see None
 159  *
 160  * @code
 161  * #include <ITapiSim.h>
 162  * int err_code = 0;
 163  * int request_id = 0;
 164  * TelSimPbType_t storage_type = 0x00;
 165  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 166  * err_code = tel_get_sim_pb_count(storage_type, &request_id);
 167  * @endcode
 168  *
 169  * @remarks None
 170  *
 171  */
 172 /*================================================================================================*/
 173 int tel_get_sim_pb_count(TapiHandle *handle, TelSimPbType_t pb_type, tapi_response_cb callback, void *user_data);
 174
 175
 176 /**
 177  * @brief  This API is used to get max text length and max number length supported by SIM phone book elementary file.
 178  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 179  *
 180  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 181  * However it just means that the API request has been transfered to the CP successfully.
 182  * The actual operation result is being delivered in the corresponding event asynchronously.
 183  *
 184  * @par Sync (or) Async:
 185  * This is an Asynchronous API.
 186  *
 187  * @par Important Notes:
 188  * - The max number length includes the storage space provided by the corresponding EXT file for a given Dialling Number file.
 189  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 190  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 191  *
 192  * @warning
 193  * - None.
 194  *
 195  * @param [in] handle
 196  * - handle from tel_init().
 197  *
 198  * @param[in] pb_type
 199  * -Different storage types to be selected in SIM. #TelSimPbType_t
 200  *
 201  * @param [in] callback
 202  * - To register callback function for result.
 203  *
 204  * @param [in] user_data
 205  * - user_data for user specification.
 206  *
 207  * @par Async Response Message:
 208  * The event associated is TAPI_EVENT_SIM_PB_ENTRY_INFO_CNF  and the event data is #TelSimPbEntryInfo_t.
 209  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 210  *
 211  * @pre
 212  *  - A dbus connection is established with #tel_init
 213  *  - The application name is registered with #tel_register_app_name
 214  *  - The application is registered events to listen asynchronous response with #tel_register_event
 215  *  - A event loop is running to listen events
 216  *
 217  * @post
 218  *  - None.
 219  *
 220  * @return Return Type (int) \n
 221  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 222  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 223  *
 224  * @par Prospective Clients:
 225  * External Apps.
 226  *
 227  * @see None
 228  *
 229  * @code
 230  * #include <ITapiSim.h>
 231  * int err_code = 0;
 232  * int request_id = 0;
 233  * TelSimPbType_t storage_type = 0x00;
 234  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 235  * err_code = tel_get_sim_pb_meta_info(storage_type, &request_id);
 236  * @endcode
 237  *
 238  * @remarks None
 239  *
 240  */
 241 /*================================================================================================*/
 242 int tel_get_sim_pb_meta_info(TapiHandle *handle, TelSimPbType_t pb_type, tapi_response_cb callback, void *user_data);
 243
 244
 245 /**
 246  * @brief  This API is used to get SIM 3G phonebook supported EFs like ANR, SNE, GRP, EMAIL etc and corresponding EFs max text length, number length and size.
 247  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 248  *
 249  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 250  * However it just means that the API request has been transfered to the CP successfully.
 251  * The actual operation result is being delivered in the corresponding event asynchronously.
 252  *
 253  * @par Sync (or) Async:
 254  * This is an Asynchronous API.
 255  *
 256  * @par Important Notes:
 257  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 258  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 259  *
 260  * @warning
 261  * - None.
 262  *
 263  * @param [in] handle
 264  * - handle from tel_init().
 265  *
 266  * @param [in] callback
 267  * - To register callback function for result.
 268  *
 269  * @param [in] user_data
 270  * - user_data for user specification.
 271  *
 272  * @par Async Response Message:
 273  * - The event associated is TAPI_SIM_EVENT_PB_3G_CAPABILITY_INFO_CNF  and the event data is #TelSimPbCapabilityInfo_t.
 274  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 275  *
 276  * @pre
 277  *  - A dbus connection is established with #tel_init
 278  *  - The application name is registered with #tel_register_app_name
 279  *  - The application is registered events to listen asynchronous response with #tel_register_event
 280  *  - A event loop is running to listen events
 281  *
 282  * @post
 283  *  - None.
 284  *
 285  * @return Return Type (int) \n
 286  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 287  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 288  *
 289  * @par Prospective Clients:
 290  * External Apps.
 291  *
 292  * @see None
 293  *
 294  * @code
 295  * #include <ITapiSim.h>
 296  * int err_code = 0;
 297  * int request_id = 0;
 298  * err_code = tel_get_sim_pb_3g_meta_info(&request_id); // you can find result by receiving asynch event response
 299  * @endcode
 300  *
 301  * @remarks None
 302  *
 303  */
 304 /*================================================================================================*/
 305 int tel_get_sim_pb_usim_meta_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 306
 307
 308 /**
 309  * @brief  This API is used to read SIM phone book entry information from given storage type.
 310  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 311  *
 312  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 313  * However it just means that the API request has been transfered to the CP successfully.
 314  * The actual operation result is being delivered in the corresponding event asynchronously.
 315  *
 316  * @par Sync (or) Async:
 317  * This is an Asynchronous API.
 318  *
 319  * @par Important Notes:
 320  * - The index ranges from 1 through to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.
 321  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 322  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 323  *
 324  * @warning
 325  * - None.
 326  *
 327  * @param [in] handle
 328  * - handle from tel_init().
 329  *
 330  * @param[in] pb_type
 331  * -Different storage types to be selected in SIM. #TelSimPbType_t
 332  *
 333  * @param[in] index
 334  * -Index for accessing the SIM data.
 335  *
 336  * @param [in] callback
 337  * - To register callback function for result.
 338  *
 339  * @param [in] user_data
 340  * - user_data for user specification.
 341  *
 342  * @par Async Response Message:
 343  * The event associated is TAPI_EVENT_SIM_PB_ACCESS_READ_CNF  and the event data is #TelSimPbRecordData_t.
 344  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 345  *
 346  * @pre
 347  *  - A dbus connection is established with #tel_init
 348  *  - The application name is registered with #tel_register_app_name
 349  *  - The application is registered events to listen asynchronous response with #tel_register_event
 350  *  - A event loop is running to listen events
 351  *
 352  * @post
 353  *  - None.
 354  *
 355  * @return Return Type (int) \n
 356  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 357  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 358  *
 359  * @par Prospective Clients:
 360  * External Apps.
 361  *
 362  * @see None
 363  *
 364  * @code
 365  * #include <ITapiSim.h>
 366  * int err_code = 0;
 367  * int request_id = 0;
 368  * unsigned short index = 1;
 369  * TelSimPbType_t storage_type = 0x00;
 370  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 371  * err_code = tel_read_sim_pb_record(storage_type, index, &request_id);
 372  * @endcode
 373  *
 374  * @remarks None
 375  *
 376  */
 377 /*================================================================================================*/
 378 int tel_read_sim_pb_record(TapiHandle *handle, TelSimPbType_t pb_type, unsigned short index, tapi_response_cb callback, void *user_data);
 379
 380
 381 /**
 382  * @brief  This API is used to add or edit SIM phone book record entry information.
 383  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 384  *
 385  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 386  * However it just means that the API request has been transfered to the CP successfully.
 387  * The actual operation result is being delivered in the corresponding event asynchronously.
 388  *
 389  * @par Sync (or) Async:
 390  * This is an Asynchronous API.
 391  *
 392  * @par Important Notes:
 393  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 394  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 395  *
 396  * @warning
 397  * - None.
 398  *
 399  *
 400  * @param [in] handle
 401  * - handle from tel_init().
 402  *
 403  * @param[in] req_data
 404  * -phonebook data which will be updated or added. #TelSimPbRecordData_t
 405  *
 406  * @param [in] callback
 407  * - To register callback function for result.
 408  *
 409  * @param [in] user_data
 410  * - user_data for user specification.
 411  *
 412  * @par Async Response Message:
 413  * The event associated is TAPI_EVENT_SIM_PB_UPDATE_CNF  and the event data is #TelSimPbUpdateResp_t.
 414  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 415  *
 416  * @pre
 417  *  - A dbus connection is established with #tel_init
 418  *  - The application name is registered with #tel_register_app_name
 419  *  - The application is registered events to listen asynchronous response with #tel_register_event
 420  *  - A event loop is running to listen events
 421  *
 422  * @post
 423  *  - None.
 424  *
 425  * @return Return Type (int) \n
 426  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 427  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 428  *
 429  * @par Prospective Clients:
 430  * External Apps.
 431  *
 432  * @see None
 433  *
 434  * @code
 435  * #include <ITapiSim.h>
 436  * int err_code = 0;
 437  * int request_id = 0;
 438  * unsigned short index = 1;
 439  * TelSimPbRecordData_t data;
 440  * data.StorageFileType  = TAPI_SIM_PB_3GSIM; // usim phonebook
 441  * data.Index  = 1; // index which will be updated
 442  * data.NextIndex  = 0;
 443  * //data.ContactInfo will be added
 444  * err_code = tel_update_sim_pb_record(&data, &request_id);
 445  * @endcode
 446  *
 447  * @remarks None
 448  *
 449  */
 450 /*================================================================================================*/
 451 int tel_update_sim_pb_record(TapiHandle *handle, const TelSimPbRecord_t *req_data, tapi_response_cb callback, void *user_data);
 452
 453
 454 /**
 455  * @brief  This API is used to delete a SIM phonebook record.
 456  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 457  *
 458  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 459  * However it just means that the API request has been transfered to the CP successfully.
 460  * The actual operation result is being delivered in the corresponding event asynchronously.
 461  *
 462  * @par Sync (or) Async:
 463  * This is an Asynchronous API.
 464  *
 465  * @par Important Notes:
 466  * - The index ranges from 1 through to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.
 467  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 468  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 469  *
 470  * @warning
 471  * - None.
 472  *
 473  *
 474  * @param [in] handle
 475  * - handle from tel_init().
 476  *
 477  * @param[in] pb_type
 478  * -Different storage types to be selected in SIM. #TelSimPbType_t
 479  *
 480  * @param[in] index
 481  * -Index of the record to be deleted.
 482  *
 483  * @param [in] callback
 484  * - To register callback function for result.
 485  *
 486  * @param [in] user_data
 487  * - user_data for user specification.
 488  *
 489  * @par Async Response Message:
 490  * The event associated is TAPI_EVENT_SIM_PB_DELETE_CNF  and the event data is #TelSimPbUpdateResp_t.
 491  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 492  *
 493  * @pre
 494  *  - A dbus connection is established with #tel_init
 495  *  - The application name is registered with #tel_register_app_name
 496  *  - The application is registered events to listen asynchronous response with #tel_register_event
 497  *  - A event loop is running to listen events
 498  *
 499  * @post
 500  *  - None.
 501  *
 502  * @return Return Type (int) \n
 503  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 504  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 505  *
 506  * @par Prospective Clients:
 507  * External Apps.
 508  *
 509  * @see None
 510  *
 511  * @code
 512  * #include <ITapiSim.h>
 513  * int err_code = 0;
 514  * int request_id = 0;
 515  * unsigned short index = 1;
 516  * TelSimPbType_t storage_type = 0x00;
 517  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 518  * err_code = tel_delete_sim_pb_record(storage_type, index, &request_id);
 519  * @endcode
 520  *
 521  * @remarks None
 522  *
 523  */
 524 /*================================================================================================*/
 525 int tel_delete_sim_pb_record(TapiHandle *handle, TelSimPbType_t pb_type, unsigned short index, tapi_response_cb callback, void *user_data);
 526
 527 #ifdef __cplusplus
 528 }
 529 #endif
 530
 531 #endif  /* _ITAPI_PHONEBOOK_H_ */
 532
 533 /**
 534 * @}
 535 */