include/contacts_sim.h

   1 /*
   2  * Contacts Service
   3  *
   4  * Copyright (c) 2010 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20
  21 #ifndef __TIZEN_SOCIAL_CONTACTS_SIM_H__
  22 #define __TIZEN_SOCIAL_CONTACTS_SIM_H__
  23
  24
  25 #include <tizen.h>
  26
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33
  34 /**
  35  * @file contacts_sim.h
  36  */
  37
  38
  39 /**
  40  * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
  41  * @defgroup CAPI_SOCIAL_CONTACTS_SVC_SIM_MODULE SIM
  42  * @brief The contacts SIM API provides the set of definitions and interfaces that enable application developers to get/set data from/to SIM card.
  43  * @section CAPI_SOCIAL_CONTACTS_SVC_SIM_MODULE_HEADER Required Header
  44  *          \#include <contacts.h>
  45  * @section CAPI_SOCIAL_CONTACTS_SVC_SIM_MODULE_FEATURE Related Features
  46  *          This API is related with the following features:\n
  47  *          - %http://tizen.org/feature/network.telephony\n
  48  *          It is recommended to design feature related codes in your application for reliability. \n
  49  *          You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n
  50  *          To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK. \n
  51  *          More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
  52  * <BR>
  53  * @{
  54  */
  55
  56
  57 /**
  58  * @deprecated Deprecated since 3.0. Use contacts_sim_import_all_contacts_by_sim_slot_no() instead.
  59  * @brief Imports all contacts from first SIM to Contacts Database.
  60  * @since_tizen @if MOBILE 2.3 @endif
  61  * @privlevel public
  62  * @privilege %http://tizen.org/privilege/contact.write
  63  * @return @c 0 on success,
  64  *         otherwise a negative error value
  65  * @retval #CONTACTS_ERROR_NONE Successful
  66  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  67  * @retval #CONTACTS_ERROR_NO_DATA Requested data does not exist
  68  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
  69  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  70  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
  71  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  72  * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
  73  * @pre contacts_connect() should be called to open a connection to the contacts service.
  74  * @see contacts_connect()
  75  */
  76 int contacts_sim_import_all_contacts(void) TIZEN_DEPRECATED_API;
  77
  78
  79 /**
  80  * @deprecated Deprecated since 3.0. Use contacts_sim_get_initialization_status_by_sim_slot_no() instead.
  81  * @brief Checks whether first SIM initialization is completed.
  82  * @since_tizen @if MOBILE 2.3 @endif
  83  * @privlevel public
  84  * @privilege %http://tizen.org/privilege/contact.read
  85  * @param[out] completed @c true if SIM is initialized,
  86  *                       otherwise @c false if SIM is not initialized
  87  * @return @c 0 on success,
  88  *         otherwise a negative error value
  89  * @retval #CONTACTS_ERROR_NONE Successful
  90  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  91  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
  92  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  93  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
  94  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  95  * @pre contacts_connect() should be called to open a connection to the contacts service.
  96  * @see contacts_connect()
  97  */
  98 int contacts_sim_get_initialization_status(bool *completed) TIZEN_DEPRECATED_API;
  99
 100
 101 /**
 102  * @brief Called whenever a contact is imported.
 103  * @since_tizen 3.0
 104  * @param[in] total The number of contacts that will be imported
 105  * @param[in] imported_cnt The number of already imported contacts
 106  * @param[in] user_data The user data passed from the callback registration function
 107  * @return @c true to continue with the import of contacts
 108  *         otherwise @c false to stop the import of contacts
 109  * @pre contacts_sim_import_all_contacts_by_sim_slot_no() will invoke this callback.
 110  * @see contacts_sim_import_all_contacts_by_sim_slot_no()
 111  */
 112 typedef bool (*contacts_sim_import_progress_cb)(int total, int imported_cnt, void *user_data);
 113
 114
 115 /**
 116  * @brief Imports all contacts from SIM of the given SIM slot number to the Contacts Database.
 117  * @details This function invokes contacts_sim_import_progress_cb() to indicate the progress of imports whenever a contact is imported.
 118  * @since_tizen 3.0
 119  * @privlevel public
 120  * @privilege %http://tizen.org/privilege/contact.write
 121  * @param[in] sim_slot_no The SIM slot number; 0 means first SIM, 1 means second SIM
 122  * @param[in] callback The callback function to invoke
 123  * @param[in] user_data The user data to be passed to the callback function
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  * @retval #CONTACTS_ERROR_NONE Successful
 127  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 128  * @retval #CONTACTS_ERROR_NO_DATA Requested data does not exist
 129  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
 130  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 131  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
 132  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 133  * @pre contacts_connect() should be called to open a connection to the contacts service.
 134  * @see contacts_connect()
 135  * @see contacts_sim_import_progress_cb()
 136  */
 137 int contacts_sim_import_all_contacts_by_sim_slot_no(int sim_slot_no, contacts_sim_import_progress_cb callback, void *user_data);
 138
 139
 140 /**
 141  * @brief Checks whether SIM of the given SIM slot number is initialized.
 142  * @since_tizen 3.0
 143  * @privlevel public
 144  * @privilege %http://tizen.org/privilege/contact.read
 145  * @param[in] sim_slot_no The SIM slot number; 0 means first SIM, 1 means second SIM
 146  * @param[out] completed @c true if SIM is initialized,
 147  *                       otherwise @c false if SIM is not initialized
 148  * @return @c 0 on success,
 149  *         otherwise a negative error value
 150  * @retval #CONTACTS_ERROR_NONE Successful
 151  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 152  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
 153  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 154  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
 155  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 156  * @pre contacts_connect() should be called to open a connection to the contacts service.
 157  * @see contacts_connect()
 158  */
 159 int contacts_sim_get_initialization_status_by_sim_slot_no(int sim_slot_no, bool *completed);
 160
 161
 162 /**
 163  * @}
 164  */
 165
 166
 167 #ifdef __cplusplus
 168 }
 169 #endif
 170
 171
 172 #endif /* __TIZEN_SOCIAL_CONTACTS_SIM_H__ */
 173