include/smartthings_notification.h

   1  /*
   2  * Copyright (c) 2018 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_NOTIFICATION_H__
  18 #define __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_NOTIFICATION_H__
  19
  20 #include <smartthings_resource.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @file smartthings_notification.h
  28  */
  29
  30 /**
  31  * @addtogroup CAPI_SMARTTHINGS_THING_NOTIFICATION_MODULE
  32  * @{
  33  */
  34
  35 /**
  36  * @brief Enumeration for the type of notification.
  37  * @since_ses 1
  38  */
  39 typedef enum {
  40         SMARTTHINGS_NOTIFICATION_TYPE_ALERT = 1,    /**< Alert type */
  41         SMARTTHINGS_NOTIFICATION_TYPE_NOTICE,       /**< Notice type */
  42         SMARTTHINGS_NOTIFICATION_TYPE_EVENT,        /**< Event type */
  43         SMARTTHINGS_NOTIFICATION_TYPE_INFO,         /**< Info type */
  44         SMARTTHINGS_NOTIFICATION_TYPE_WARNING       /**< Warning type */
  45 } smartthings_notification_type_e;
  46
  47
  48 /**
  49  * @brief The SmartThings push message handle.
  50  * @since_ses 1
  51  */
  52 typedef struct smartthings_push_msg_s* smartthings_push_msg_h;
  53
  54 /**
  55  * @brief Creates a SmartThings push message handle.
  56  * @since_ses 1
  57  *
  58  * @remarks The @a handle must be released using smartthings_push_msg_destroy().
  59  *
  60  * @param[out] handle The SmartThings push message handle to be newly created on success
  61  *
  62  * @return @c 0 on success,
  63  *         otherwise a negative error value
  64  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
  65  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
  66  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
  67  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
  68  *
  69  * @see smartthings_push_msg_destroy()
  70  */
  71 int smartthings_push_msg_create(smartthings_push_msg_h *handle);
  72
  73 /**
  74  * @brief Destroys a SmartThings push message handle and releases all its resources.
  75  * @since_ses 1
  76  *
  77  * @param[in] handle The SmartThings push message handle
  78  *
  79  * @return @c 0 on success,
  80  *         otherwise a negative error value
  81  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
  82  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
  83  *
  84  * @see smartthings_push_msg_create()
  85  */
  86 int smartthings_push_msg_destroy(smartthings_push_msg_h handle);
  87
  88 /**
  89  * @brief Sets a URI for the push message.
  90  * @since_ses 1
  91  *
  92  * @param[in] handle The SmartThings push message handle
  93  * @param[in] uri The URI of push message to set
  94  *
  95  * @return @c 0 on success,
  96  *         otherwise a negative error value
  97  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
  98  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
  99  *
 100  */
 101 int smartthings_push_msg_set_uri(smartthings_push_msg_h handle, const char *uri);
 102
 103 /**
 104  * @brief Sets a type for the push message.
 105  * @since_ses 1
 106  *
 107  * @param[in] handle The SmartThings push message handle
 108  * @param[in] type The type of push message to set
 109  *
 110  * @return @c 0 on success,
 111  *         otherwise a negative error value
 112  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 113  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 114  *
 115  */
 116 int smartthings_push_msg_set_type(smartthings_push_msg_h handle, smartthings_notification_type_e type);
 117
 118 /**
 119  * @brief Sets a code for the push message.
 120  * @since_ses 1
 121  *
 122  * @param[in] handle The SmartThings push message handle
 123  * @param[in] code The code of push message to set
 124  *
 125  * @return @c 0 on success,
 126  *         otherwise a negative error value
 127  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 128  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 129  *
 130  */
 131 int smartthings_push_msg_set_code(smartthings_push_msg_h handle, const char *code);
 132
 133 /**
 134  * @brief Sets a payload for the push message.
 135  * @since_ses 1
 136  *
 137  * @param[in] handle The SmartThings push message handle
 138  * @param[in] payload The payload of push message to set
 139  *
 140  * @return @c 0 on success,
 141  *         otherwise a negative error value
 142  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 143  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 144  *
 145  */
 146 int smartthings_push_msg_set_payload(smartthings_push_msg_h handle, smartthings_payload_h payload);
 147
 148 /**
 149  * @brief Sends the push message.
 150  * @since_ses 1
 151  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 152  *            %http://tizen.org/privilege/appmanager.launch \n
 153  *            %http://tizen.org/privilege/datasharing \n
 154  *            %http://tizen.org/privilege/internet
 155  *
 156  * @param[in] st_h The SmartThings resource handle
 157  * @param[in] push_msg_h The SmartThings push message handle
 158  *
 159  * @return @c 0 on success,
 160  *         otherwise a negative error value
 161  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 162  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 163  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 164  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 165  */
 166 int smartthings_send_push_msg(smartthings_resource_h st_h, smartthings_push_msg_h push_msg_h);
 167
 168
 169 /**
 170  * @brief The SmartThings notification message handle.
 171  * @since_ses 1
 172  */
 173 typedef struct smartthings_notification_msg_s* smartthings_notification_msg_h;
 174
 175
 176 /**
 177  * @brief Creates a SmartThings notification message handle.
 178  * @since_ses 1
 179  *
 180  * @remarks The @a handle must be released using smartthings_notification_msg_destroy().
 181  *
 182  * @param[out] handle The SmartThings notification message handle to be newly created on success
 183  *
 184  * @return @c 0 on success,
 185  *         otherwise a negative error value
 186  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 187  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 188  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 189  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 190  *
 191  * @see smartthings_notification_msg_destroy()
 192  */
 193 int smartthings_notification_msg_create(smartthings_notification_msg_h *handle);
 194
 195 /**
 196  * @brief Destroys a SmartThings notification message handle and releases all its resources.
 197  * @since_ses 1
 198  *
 199  * @param[in] handle The SmartThings notification message handle
 200  *
 201  * @return @c 0 on success,
 202  *         otherwise a negative error value
 203  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 204  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 205  *
 206  * @see smartthings_notification_msg_create()
 207  */
 208 int smartthings_notification_msg_destroy(smartthings_notification_msg_h handle);
 209
 210 /**
 211  * @brief Sets a URI for the notification message.
 212  * @since_ses 1
 213  *
 214  * @param[in] handle The SmartThings notification message handle
 215  * @param[in] uri The URI of notification message to set
 216  *
 217  * @return @c 0 on success,
 218  *         otherwise a negative error value
 219  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 220  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 221  *
 222  */
 223 int smartthings_notification_msg_set_uri(smartthings_notification_msg_h handle, const char *uri);
 224
 225 /**
 226  * @brief Sets a type for the notification message.
 227  * @since_ses 1
 228  *
 229  * @param[in] handle The SmartThings notification message handle
 230  * @param[in] type The type of notification message to set
 231  *
 232  * @return @c 0 on success,
 233  *         otherwise a negative error value
 234  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 235  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 236  *
 237  */
 238 int smartthings_notification_msg_set_type(smartthings_notification_msg_h handle, smartthings_notification_type_e type);
 239
 240 /**
 241  * @brief Sets a payload for the notification message.
 242  * @since_ses 1
 243  *
 244  * @param[in] handle The SmartThings notification message handle
 245  * @param[in] name The name of payload
 246  * @param[in] payload The payload of notification message to set
 247  *
 248  * @return @c 0 on success,
 249  *         otherwise a negative error value
 250  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 251  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 252  *
 253  */
 254 int smartthings_notification_msg_set_payload(smartthings_notification_msg_h handle, const char *name, smartthings_payload_h payload);
 255
 256 /**
 257  * @brief Sends the notification message.
 258  * @since_ses 1
 259  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 260  *            %http://tizen.org/privilege/appmanager.launch \n
 261  *            %http://tizen.org/privilege/datasharing \n
 262  *            %http://tizen.org/privilege/internet
 263  *
 264  * @param[in] st_h The SmartThings resource handle
 265  * @param[in] notification_msg_h The SmartThings notification message handle
 266  *
 267  * @return @c 0 on success,
 268  *         otherwise a negative error value
 269  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 270  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 271  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 272  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 273  */
 274 int smartthings_send_notification_msg(smartthings_resource_h st_h, smartthings_notification_msg_h notification_msg_h);
 275
 276
 277 /**
 278  * @}
 279  */
 280
 281 #ifdef __cplusplus
 282 }
 283 #endif
 284
 285 #endif /* __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_NOTIFICATION_H__ */