include/calendar_service.h

   1 /*
   2  * Calendar Service
   3  *
   4  * Copyright (c) 2012 - 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 #ifndef __TIZEN_SOCIAL_CALENDAR_SERVICE_H__
  21 #define __TIZEN_SOCIAL_CALENDAR_SERVICE_H__
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file calendar_service.h
  29  */
  30
  31 /**
  32  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
  33  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_COMMON_MODULE Common
  34  * @brief The calendar common API provides the set of definitions and interfaces to initialize and deinitialize.
  35  *
  36  * @section CAPI_SOCIAL_CALENDAR_SVC_COMMON_MODULE_HEADER Required Header
  37  *  \#include <calendar.h>
  38  *
  39  * <BR>
  40  * @{
  41  */
  42
  43 /**
  44  * @brief Connects to the calendar service.
  45  *
  46  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  47  *
  48  * @remarks Opening the connection is necessary to access the calendar database and perform operations such as fetching, inserting, or updating records.\n
  49  *          The execution of calendar_connect() and calendar_disconnect() could slow down your application, so you are recommended not to call them frequently.
  50  *
  51  * @return  @c 0 on success,
  52  *          otherwise a negative error value
  53  * @retval  #CALENDAR_ERROR_NONE                Successful
  54  * @retval  #CALENDAR_ERROR_DB_FAILED           Database operation failure
  55  * @retval  #CALENDAR_ERROR_OUT_OF_MEMORY       Out of memory
  56  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
  57  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
  58  * @retval  #CALENDAR_ERROR_PERMISSION_DENIED   Permission denied. This application does not have the privilege to call this method
  59  * @retval  #CALENDAR_ERROR_IPC                 Unknown IPC error
  60  * @retval  #CALENDAR_ERROR_SYSTEM              Error from another modules
  61  *
  62  * @see  calendar_disconnect()
  63  */
  64 int calendar_connect(void);
  65
  66 /**
  67  * @brief Disconnects from the calendar service.
  68  *
  69  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  70  *
  71  * @remarks If there is no opened connection, this function returns #CALENDAR_ERROR_DB_FAILED.
  72  *
  73  * @return  @c 0 on success,
  74  *          otherwise a negative error value
  75  * @retval  #CALENDAR_ERROR_NONE                Successful
  76  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
  77  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
  78  * @retval  #CALENDAR_ERROR_IPC                 Unknown IPC error
  79  *
  80  * @see calendar_connect()
  81  */
  82 int calendar_disconnect(void);
  83
  84 /**
  85  * @brief Connects to the calendar service on a thread.
  86  *
  87  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  88  *
  89  * @remarks Opening a connection is necessary to access the calendar database and perform operations such as fetching, inserting, or updating records.\n
  90  *          On a thread environment with calendar_connect(), request in one thread could fail, while another request connection is working in the other thread.
  91  *          To prevent request failure, calendar_connect_on_thread() is recommended.
  92  *
  93  * @return  @c 0 on success,
  94  *          otherwise a negative error value
  95  * @retval  #CALENDAR_ERROR_NONE               Successful
  96  * @retval  #CALENDAR_ERROR_DB_FAILED          Database operation failure
  97  * @retval  #CALENDAR_ERROR_PERMISSION_DENIED  Permission denied. This application does not have the privilege to call this method
  98  *
  99  * @see  calendar_disconnect_on_thread()
 100  */
 101 int calendar_connect_on_thread(void);
 102
 103 /**
 104  * @brief Disconnects from the calendar service on a thread.
 105  *
 106  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 107  *
 108  * @remarks If there is no opened connection, this function returns #CALENDAR_ERROR_DB_FAILED.
 109  *
 110  * @return  @c 0 on success,
 111  *          otherwise a negative error value
 112  * @retval  #CALENDAR_ERROR_NONE                Successful
 113  * @retval  #CALENDAR_ERROR_DB_FAILED           Database operation failure
 114  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 115  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 116  *
 117  * @see calendar_connect_on_thread()
 118  */
 119 int calendar_disconnect_on_thread(void);
 120
 121 /**
 122  * @brief Connects to the calendar service.
 123  *
 124  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 125  *
 126  * @remarks Opening a connection is necessary to access the calendar database and perform operations such as fetching, inserting, or updating records.\n
 127  *          Before the calendar-service daemon is ready, if you call calendar_connect(), it could fail.
 128  *          It is recommended to call this API with #CALENDAR_CONNECT_FLAG_RETRY flags in such a situation.
 129  *
 130  * @param[in]   flags  calendar_connect_flag
 131  *
 132  * @return  @c 0 on success,
 133  *          otherwise a negative error value
 134  * @retval  #CALENDAR_ERROR_NONE                            Successful
 135  * @retval  #CALENDAR_ERROR_DB_FAILED           Database operation failure
 136  * @retval  #CALENDAR_ERROR_OUT_OF_MEMORY       Out of memory
 137  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 138  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 139  * @retval  #CALENDAR_ERROR_PERMISSION_DENIED   Permission denied. This application does not have the privilege to call this method.
 140  * @retval  #CALENDAR_ERROR_IPC                 Unknown IPC error
 141  * @retval  #CALENDAR_ERROR_SYSTEM              Error from another modules
 142  *
 143  * @see  calendar_disconnect(), CALENDAR_CONNECT_FLAG_RETRY
 144  */
 145 int calendar_connect_with_flags(unsigned int flags);
 146
 147 /**
 148  * @}
 149  */
 150
 151 #ifdef __cplusplus
 152 }
 153 #endif
 154
 155 #endif /* __TIZEN_SOCIAL_CALENDAR_SERVICE_H__ */
 156