include/contacts_service.h

   1 /*
   2  * Contacts Service
   3  *
   4  * Copyright (c) 2010 - 2012 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 #ifndef __TIZEN_SOCIAL_CONTACTS_SERVICE_H__
  20 #define __TIZEN_SOCIAL_CONTACTS_SERVICE_H__
  21
  22 #ifndef API
  23 #define API __attribute__ ((visibility("default")))
  24 #endif
  25
  26 #ifdef __cplusplus
  27 extern "C"
  28 {
  29 #endif
  30
  31 /**
  32  * @file contacts_service.h
  33  */
  34
  35 /**
  36  * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
  37  * @defgroup CAPI_SOCIAL_CONTACTS_SVC_COMMON_MODULE Common
  38  *
  39  * @brief The contacts common API provides the set of definitions and interfaces to initialize and deinitialize.
  40  *
  41  * @section CAPI_SOCIAL_CONTACTS_SVC_COMMON_MODULE_HEADER Required Header
  42  *  \#include <contacts.h>
  43  *
  44  * <BR>
  45  * @{
  46  */
  47
  48 /**
  49  * @brief Connects to the contacts service.
  50  *
  51  * @since_tizen 2.3
  52  *
  53  * @remarks Connection opening is necessary to access the contacts server such as fetching, inserting, or updating records.\n
  54  *          The execution of contacts_connect() and contacts_disconnect() could slow down your application. So it is not recommended to call them frequently.
  55  *
  56  * @return  @c 0 on success,
  57  *          otherwise a negative error value
  58  *
  59  * @retval  #CONTACTS_ERROR_NONE                Successful
  60  * @retval  #CONTACTS_ERROR_DB                  Database operation failure
  61  * @retval  #CONTACTS_ERROR_IPC_NOT_AVALIABLE   IPC server is not available
  62  * @retval  #CONTACTS_ERROR_IPC                 IPC error
  63  * @retval  #CONTACTS_ERROR_SYSTEM              System error
  64  * @retval  #CONTACTS_ERROR_PERMISSION_DENIED   Permission denied. This application does not have the privilege to call this method.
  65  *
  66  * @see contacts_disconnect()
  67  */
  68 int contacts_connect(void);
  69
  70 /**
  71  * @brief Disconnects from the contacts service.
  72  *
  73  * @since_tizen 2.3
  74  *
  75  * @remarks If there is no opened connection, this function returns #CONTACTS_ERROR_DB.
  76  *
  77  * @return  @c 0 on success,
  78  *          otherwise a negative error value
  79  *
  80  * @retval  #CONTACTS_ERROR_NONE                  Successful
  81  * @retval  #CONTACTS_ERROR_INVALID_PARAMETER     Invalid parameter
  82  * @retval  #CONTACTS_ERROR_DB                    Database operation failure
  83  * @retval  #CONTACTS_ERROR_IPC                   IPC error
  84  *
  85  * @see contacts_connect()
  86  */
  87 int contacts_disconnect(void);
  88
  89 /**
  90  * @brief Connects to the contacts service with a connection on another thread.
  91  *
  92  * @since_tizen 2.3
  93  *
  94  * @remarks Opening connection is necessary to access the contact server and to perform operations such as fetching, inserting, or updating records.\n
  95  *          On multiple thread environment with contacts_connect(), request can be failed in one thread, while another request is working by the connection in the other thread.
  96  *          To prevent request fail, contacts_connect_on_thread() is recommended. Then new connection is set for the thread.
  97  *
  98  * @return  @c 0 on success,
  99  *          otherwise a negative error value
 100  *
 101  * @retval  #CONTACTS_ERROR_NONE                Successful
 102  * @retval  #CONTACTS_ERROR_OUT_OF_MEMORY       Out of memory
 103  * @retval  #CONTACTS_ERROR_DB                  Database operation failure
 104  * @retval  #CONTACTS_ERROR_IPC_NOT_AVALIABLE   IPC server is not available
 105  * @retval  #CONTACTS_ERROR_IPC                 IPC error
 106  * @retval  #CONTACTS_ERROR_SYSTEM              System error
 107  * @retval  #CONTACTS_ERROR_INTERNAL            Internal error
 108  * @retval  #CONTACTS_ERROR_PERMISSION_DENIED   Permission denied. This application does not have the privilege to call this method.
 109  *
 110  * @see  contacts_disconnect_on_thread()
 111  */
 112 int contacts_connect_on_thread(void);
 113
 114 /**
 115  * @brief Disconnects from the contacts service.
 116  *
 117  * @since_tizen 2.3
 118  *
 119  * @return  @c 0 on success,
 120  *          otherwise a negative error value
 121  *
 122  * @retval  #CONTACTS_ERROR_NONE                  Successful
 123  * @retval  #CONTACTS_ERROR_INVALID_PARAMETER     Invalid parameter
 124  * @retval  #CONTACTS_ERROR_DB                    Database operation failure
 125  * @retval  #CONTACTS_ERROR_IPC                   IPC error
 126  *
 127  * @see contacts_connect_on_thread()
 128  */
 129 int contacts_disconnect_on_thread(void);
 130
 131
 132 /**
 133  * @brief Definition for contacts_connect_with_flags(). If it is called the API with this flag, then retry to call contacts_connect() for several times.
 134  *
 135  * @since_tizen 2.3
 136  *
 137  * @see contacts_connect_with_flags()
 138  */
 139 #define CONTACTS_CONNECT_FLAG_RETRY     0x00000001
 140
 141 /**
 142  * @brief Definition for default flag of contacts_connect_with_flags().
 143  *
 144  * @since_tizen 2.3
 145  *
 146  * @see contacts_connect_with_flags()
 147  */
 148 #define CONTACTS_CONNECT_FLAG_NONE      0
 149
 150 /**
 151  * @brief Connects to the contacts service.
 152  *
 153  * @since_tizen 2.3
 154  *
 155  * @param[in]   flags   connection flag
 156  *
 157  * @remarks Connection opening is necessary to access the contacts server such as fetching, inserting, or updating records.\n
 158  *          Before contacts-service daemon is ready, if you call contacts_connect(), it will fail.
 159  *          To prevent it, if you call this API with @ref CONTACTS_CONNECT_FLAG_RETRY flags, it will retry several time.\n
 160  *          To close the connection, contacts_disconnect() should be called.
 161  *
 162  * @return  @c 0 on success,
 163  *          otherwise a negative error value
 164  *
 165  * @retval  #CONTACTS_ERROR_NONE                Successful
 166  * @retval  #CONTACTS_ERROR_DB                  Database operation failure
 167  * @retval  #CONTACTS_ERROR_IPC_NOT_AVALIABLE   IPC server is not available
 168  * @retval  #CONTACTS_ERROR_IPC                 IPC error
 169  * @retval  #CONTACTS_ERROR_SYSTEM              System error
 170  * @retval  #CONTACTS_ERROR_PERMISSION_DENIED   Permission denied. This application does not have the privilege to call this method.
 171  *
 172  * @see  contacts_disconnect()
 173  */
 174 int contacts_connect_with_flags(unsigned int flags);
 175
 176 // TODO: Remove
 177 int contacts_connect2(void);
 178 int contacts_disconnect2(void);
 179
 180
 181 /**
 182  * @}
 183  */
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif
 188
 189
 190 #endif //__TIZEN_SOCIAL_CONTACTS_SERVICE_H__