wearable/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  * TelSimPbList_t pb_list = {0,};
  93  * int pPbInitCompleted = 0; // init or not
  94  * TapiHandle *handle; // handle given by tel_init()
  95  *
  96  * // GET SIM PHONEBOOK INIT INFORMATION
  97  * err_code = tel_get_sim_pb_init_info(handle, &pPbInitCompleted, &pb_list);
  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 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  * TapiHandle *handle; // handle given by tel_init()
 165  * tapi_response_cb callback; // Initialized callback function pointer in which response is returned
 166  * TelSimPbType_t storage_type = 0x00;
 167  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 168  * err_code = tel_get_sim_pb_count(handle, storage_type, callback, &request_id);
 169  * @endcode
 170  *
 171  * @remarks None
 172  *
 173  */
 174 /*================================================================================================*/
 175 int tel_get_sim_pb_count(TapiHandle *handle, TelSimPbType_t pb_type, tapi_response_cb callback, void *user_data);
 176
 177
 178 /**
 179  * @brief  This API is used to get max text length and max number length supported by SIM phone book elementary file.
 180  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 181  *
 182  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 183  * However it just means that the API request has been transfered to the CP successfully.
 184  * The actual operation result is being delivered in the corresponding event asynchronously.
 185  *
 186  * @par Sync (or) Async:
 187  * This is an Asynchronous API.
 188  *
 189  * @par Important Notes:
 190  * - The max number length includes the storage space provided by the corresponding EXT file for a given Dialling Number file.
 191  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 192  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 193  *
 194  * @warning
 195  * - None.
 196  *
 197  * @param [in] handle
 198  * - handle from tel_init().
 199  *
 200  * @param[in] pb_type
 201  * -Different storage types to be selected in SIM. #TelSimPbType_t
 202  *
 203  * @param [in] callback
 204  * - To register callback function for result.
 205  *
 206  * @param [in] user_data
 207  * - user_data for user specification.
 208  *
 209  * @par Async Response Message:
 210  * The event data is #TelSimPbEntryInfo_t.
 211  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 212  *
 213  * @pre
 214  *  - A dbus connection is established with #tel_init
 215  *  - The application name is registered with #tel_register_app_name
 216  *  - The application is registered events to listen asynchronous response with #tel_register_event
 217  *  - A event loop is running to listen events
 218  *
 219  * @post
 220  *  - None.
 221  *
 222  * @return Return Type (int) \n
 223  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 224  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 225  *
 226  * @par Prospective Clients:
 227  * External Apps.
 228  *
 229  * @see None
 230  *
 231  * @code
 232  * #include <ITapiSim.h>
 233  * int err_code = 0;
 234  * int request_id = 0;
 235  * TapiHandle *handle; // handle given by tel_init()
 236  * tapi_response_cb callback; // Initialized callback function pointer in which response is returned
 237  * TelSimPbType_t storage_type = 0x00;
 238  * storage_type = TAPI_SIM_PB_ADN; // ADN phonebook
 239  * err_code = tel_get_sim_pb_meta_info(handle, storage_type, callback, &request_id);
 240  * @endcode
 241  *
 242  * @remarks None
 243  *
 244  */
 245 /*================================================================================================*/
 246 int tel_get_sim_pb_meta_info(TapiHandle *handle, TelSimPbType_t pb_type, tapi_response_cb callback, void *user_data);
 247
 248
 249 /**
 250  * @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.
 251  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 252  *
 253  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 254  * However it just means that the API request has been transfered to the CP successfully.
 255  * The actual operation result is being delivered in the corresponding event asynchronously.
 256  *
 257  * @par Sync (or) Async:
 258  * This is an Asynchronous API.
 259  *
 260  * @par Important Notes:
 261  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 262  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 263  *
 264  * @warning
 265  * - None.
 266  *
 267  * @param [in] handle
 268  * - handle from tel_init().
 269  *
 270  * @param [in] callback
 271  * - To register callback function for result.
 272  *
 273  * @param [in] user_data
 274  * - user_data for user specification.
 275  *
 276  * @par Async Response Message:
 277  * The event data is #TelSimPbCapabilityInfo_t.
 278  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 279  *
 280  * @pre
 281  *  - A dbus connection is established with #tel_init
 282  *  - The application name is registered with #tel_register_app_name
 283  *  - The application is registered events to listen asynchronous response with #tel_register_event
 284  *  - A event loop is running to listen events
 285  *
 286  * @post
 287  *  - None.
 288  *
 289  * @return Return Type (int) \n
 290  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 291  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 292  *
 293  * @par Prospective Clients:
 294  * External Apps.
 295  *
 296  * @see None
 297  *
 298  * @code
 299  * #include <ITapiSim.h>
 300  * int err_code = 0;
 301  * int request_id = 0;
 302  * TapiHandle *handle; // handle given by tel_init()
 303  * tapi_response_cb callback; // Initialized callback function pointer in which response is returned
 304  * err_code = tel_get_sim_pb_usim_meta_info(handle, callback, &request_id);
 305  * @endcode
 306  *
 307  * @remarks None
 308  *
 309  */
 310 /*================================================================================================*/
 311 int tel_get_sim_pb_usim_meta_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 312
 313
 314 /**
 315  * @brief  This API is used to read SIM phone book entry information from given storage type and index.
 316  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 317  *
 318  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 319  * However it just means that the API request has been transfered to the CP successfully.
 320  * The actual operation result is being delivered in the corresponding event asynchronously.
 321  *
 322  * @par Sync (or) Async:
 323  * This is an Asynchronous API.
 324  *
 325  * @par Important Notes:
 326  * - The index ranges from 1 through to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.
 327  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 328  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 329  *
 330  * @warning
 331  * - None.
 332  *
 333  * @param [in] handle
 334  * - handle from tel_init().
 335  *
 336  * @param[in] pb_type
 337  * -Different storage types to be selected in SIM. #TelSimPbType_t
 338  *
 339  * @param[in] index
 340  * -Index for accessing the SIM data.
 341  *
 342  * @param [in] callback
 343  * - To register callback function for result.
 344  *
 345  * @param [in] user_data
 346  * - user_data for user specification.
 347  *
 348  * @par Async Response Message:
 349  * The event data is #TelSimPbRecord_t.
 350  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 351  *
 352  * @pre
 353  *  - A dbus connection is established with #tel_init
 354  *  - The application name is registered with #tel_register_app_name
 355  *  - The application is registered events to listen asynchronous response with #tel_register_event
 356  *  - A event loop is running to listen events
 357  *
 358  * @post
 359  *  - None.
 360  *
 361  * @return Return Type (int) \n
 362  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 363  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 364  *
 365  * @par Prospective Clients:
 366  * External Apps.
 367  *
 368  * @see None
 369  *
 370  * @code
 371  * #include <ITapiSim.h>
 372  * int err_code = 0;
 373  * int request_id = 0;
 374  * TapiHandle *handle; // handle given by tel_init()
 375  * tapi_response_cb callback; // Initialized callback function pointer in which response is returned
 376  * unsigned short index = 1;
 377  * TelSimPbType_t storage_type = 0x00;
 378  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 379  * err_code = tel_read_sim_pb_record(handle, storage_type, index, callback, &request_id);
 380  * @endcode
 381  *
 382  * @remarks None
 383  *
 384  */
 385 /*================================================================================================*/
 386 int tel_read_sim_pb_record(TapiHandle *handle, TelSimPbType_t pb_type, unsigned short index, tapi_response_cb callback, void *user_data);
 387
 388
 389 /**
 390  * @brief  This API is used to add or edit SIM phone book record entry information.
 391  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 392  *
 393  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 394  * However it just means that the API request has been transfered to the CP successfully.
 395  * The actual operation result is being delivered in the corresponding event asynchronously.
 396  *
 397  * @par Sync (or) Async:
 398  * This is an Asynchronous API.
 399  *
 400  * @par Important Notes:
 401  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 402  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 403  *
 404  * @warning
 405  * - None.
 406  *
 407  *
 408  * @param [in] handle
 409  * - handle from tel_init().
 410  *
 411  * @param[in] req_data
 412  * -phonebook data which will be updated or added. #TelSimPbRecordData_t
 413  *
 414  * @param [in] callback
 415  * - To register callback function for result.
 416  *
 417  * @param [in] user_data
 418  * - user_data for user specification.
 419  *
 420  * @par Async Response Message:
 421  * The event data is NULL.
 422  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 423  *
 424  * @pre
 425  *  - A dbus connection is established with #tel_init
 426  *  - The application name is registered with #tel_register_app_name
 427  *  - The application is registered events to listen asynchronous response with #tel_register_event
 428  *  - A event loop is running to listen events
 429  *
 430  * @post
 431  *  - None.
 432  *
 433  * @return Return Type (int) \n
 434  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 435  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 436  *
 437  * @par Prospective Clients:
 438  * External Apps.
 439  *
 440  * @see None
 441  *
 442  * @code
 443  * #include <ITapiSim.h>
 444  * int err_code = 0;
 445  * int request_id = 0;
 446  * TapiHandle *handle; // handle given by tel_init()
 447  * tapi_response_cb callback; // Initialized callback function pointer in which response is returned
 448  * unsigned short index = 1;
 449  * TelSimPbRecord_t data;
 450  * data.StorageFileType  = TAPI_SIM_PB_3GSIM; // usim phonebook
 451  * data.Index  = 1; // index which will be updated
 452  * data.NextIndex  = 0;
 453  * //data.ContactInfo will be added
 454  * err_code = tel_update_sim_pb_record(handle, &data, callback, &request_id);
 455  * @endcode
 456  *
 457  * @remarks None
 458  *
 459  */
 460 /*================================================================================================*/
 461 int tel_update_sim_pb_record(TapiHandle *handle, const TelSimPbRecord_t *req_data, tapi_response_cb callback, void *user_data);
 462
 463
 464 /**
 465  * @brief  This API is used to delete a SIM phonebook record.
 466  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
 467  *
 468  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 469  * However it just means that the API request has been transfered to the CP successfully.
 470  * The actual operation result is being delivered in the corresponding event asynchronously.
 471  *
 472  * @par Sync (or) Async:
 473  * This is an Asynchronous API.
 474  *
 475  * @par Important Notes:
 476  * - The index ranges from 1 through to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.
 477  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
 478  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
 479  *
 480  * @warning
 481  * - None.
 482  *
 483  *
 484  * @param [in] handle
 485  * - handle from tel_init().
 486  *
 487  * @param[in] pb_type
 488  * -Different storage types to be selected in SIM. #TelSimPbType_t
 489  *
 490  * @param[in] index
 491  * -Index of the record to be deleted.
 492  *
 493  * @param [in] callback
 494  * - To register callback function for result.
 495  *
 496  * @param [in] user_data
 497  * - user_data for user specification.
 498  *
 499  * @par Async Response Message:
 500  * The event data is NULL.
 501  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
 502  *
 503  * @pre
 504  *  - A dbus connection is established with #tel_init
 505  *  - The application name is registered with #tel_register_app_name
 506  *  - The application is registered events to listen asynchronous response with #tel_register_event
 507  *  - A event loop is running to listen events
 508  *
 509  * @post
 510  *  - None.
 511  *
 512  * @return Return Type (int) \n
 513  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 514  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 515  *
 516  * @par Prospective Clients:
 517  * External Apps.
 518  *
 519  * @see None
 520  *
 521  * @code
 522  * #include <ITapiSim.h>
 523  * int err_code = 0;
 524  * int request_id = 0;
 525  * TapiHandle *handle; // handle given by tel_init()
 526  * tapi_response_cb callback; // Initialized callback function pointer in which response is returned
 527  * unsigned short index = 1;
 528  * TelSimPbType_t storage_type = 0x00;
 529  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
 530  * err_code = tel_delete_sim_pb_record(handle, storage_type, index, callback, &request_id);
 531  * @endcode
 532  *
 533  * @remarks None
 534  *
 535  */
 536 /*================================================================================================*/
 537 int tel_delete_sim_pb_record(TapiHandle *handle, TelSimPbType_t pb_type, unsigned short index, tapi_response_cb callback, void *user_data);
 538
 539 #ifdef __cplusplus
 540 }
 541 #endif
 542
 543 #endif  /* _ITAPI_PHONEBOOK_H_ */
 544
 545 /**
 546 * @}
 547 */