inc/st_things.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 __ST_THINGS_H__
  18 #define __ST_THINGS_H__
  19
  20 #include <stdint.h>
  21 #include <stdbool.h>
  22
  23 #ifdef __ST_THINGS_RTOS__
  24 #include <st_things/st_things_types.h>
  25 #else
  26 #include "st_things_types.h"
  27 #endif // __ST_THINGS_RTOS__
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif /* __cplusplus */
  32
  33 /**
  34  * @brief Set prefix paths (ReadOnly and ReadWrite) for configuration files for the device.
  35  *            This is Optional API, and should be used if relative location is used in
  36  *            filePath variable in JSON Configuration file.
  37  * @param[in] ro_path Prefix Path for Read Only directory location.
  38  * @param[in] rw_path Prefix Path for Read Write directory location.
  39  * @return @c 0 on success, otherwise a negative error value
  40  * @retval #ST_THINGS_ERROR_NONE Successful
  41  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter(both ro_path and rw_path are NULL).
  42  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
  43  * @retval #ST_THINGS_ERROR_STACK_ALREADY_INITIALIZED Stack already initialized.
  44  *         To set Prefix Paths, stack should be deinitilized first by calling st_things_deinitialize().
  45  * @retval #ST_THINGS_ERROR_STACK_RUNNING Stack is currently running.
  46  *         To set Prefix Paths, stack should be stopped first by calling st_things_stop()
  47  *         and then deinitialized by calling st_things_deinitialize().
  48  */
  49 int st_things_set_configuration_prefix_path(const char* ro_path, const char* rw_path);
  50
  51 /**
  52  * @brief Initializes things stack and returns whether easy-setup is completed or not.
  53  *            Easy-setup enable users to acquire the ownership of things and to connect the things with the cloud.
  54  *            After performing easy-setup, users can access things from anywhere through the cloud.
  55  *            In things stack, easy-setup is a primary and the first operation to be performed on the thing.
  56  *            Application running on the thing can know whether easy-setup is done already or not.
  57  *            If easy-setup is done, app can start the things stack by calling st_things_start().
  58  *            If easy-setup is not done, app can either wait for the user interaction before starting the things stack or
  59  *            start the things stack directly without waiting for any events(This case is for those things which doesn't
  60  *            support input capability and for all other unknown cases).
  61  *            To use a new json file after initialization, stack should be deinitialized
  62  *            and stopped(if its started already).
  63  * @param[in] json_path Path to Json file which defines a thing. Definition includes the device information,
  64  *                                       resources and their properties, configuration info for connectivity and easy-setup, etc.
  65  * @param[out] easysetup_complete Indicates whether easysetup is completed already or not.
  66  * @return @c 0 on success, otherwise a negative error value
  67  * @retval #ST_THINGS_ERROR_NONE Successful
  68  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
  69  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
  70  * @retval #ST_THINGS_ERROR_STACK_ALREADY_INITIALIZED Stack already initialized.
  71  *         To initialize again, stack should be deinitilized first by calling st_things_deinitialize().
  72  * @retval #ST_THINGS_ERROR_STACK_RUNNING Stack is currently running.
  73  *         To initialize again, stack should be stopped first by calling st_things_stop()
  74  *         and then deinitialized by calling st_things_deinitialize().
  75  */
  76 int st_things_initialize(const char *json_path, bool *easysetup_complete);
  77
  78 /**
  79  * @brief Deinitializes things stack.
  80  *        Stack should have been initialized before calling this API.
  81  * @return @c 0 on success, otherwise a negative error value
  82  * @retval #ST_THINGS_ERROR_NONE Successful
  83  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
  84  * @retval #ST_THINGS_ERROR_STACK_NOT_INITIALIZED Stack is not initialized.
  85  *         Initialize the stack by calling st_things_initialize().
  86  * @retval #ST_THINGS_ERROR_STACK_RUNNING Stack is currently running.
  87  *         Before deinitialize, stack needs to be stopped by calling st_things_stop().
  88  */
  89 int st_things_deinitialize(void);
  90
  91 /**
  92  * @brief Callback for handling GET request.
  93  * @param[in]  req_msg GET request message.
  94  * @param[out] resp_rep Representation that will be set to payload of response.
  95  * @return @c true in case of success, otherwise @c false
  96  */
  97 typedef bool (*st_things_get_request_cb)(st_things_get_request_message_s *req_msg, st_things_representation_s *resp_rep);
  98
  99 /**
 100  * @brief Callback for handling SET(POST) request.
 101  * @param[in]  req_msg SET request message.
 102  * @param[out] resp_rep Representation that will be set to payload of response.
 103  * @return @c true in case of success, otherwise @c false
 104  */
 105 typedef bool (*st_things_set_request_cb)(st_things_set_request_message_s *req_msg, st_things_representation_s *resp_rep);
 106
 107 /**
 108  * @brief Callback registration function for handling request messages.
 109  * @details The callbacks ensure that a request message will be carried with one of the resource uris from json file of st_things_start().
 110  * @remarks Only one callback function can be set with this API.\n
 111  *          If multiple callbacks are set, the last one is registered only.\n
 112  *          And the callbacks are called in the internal thread, which is not detached,\n
 113  *          so application should return it to get the next callbacks.
 114  * @param[in] get_cb Reference of the callback function to handle GET request.
 115  * @param[in] set_cb Reference of the callback function to handle SET(POST) request.
 116  * @return @c 0 on success, otherwise a negative error value
 117  * @retval #ST_THINGS_ERROR_NONE Successful
 118  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
 119  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 120  */
 121 int st_things_register_request_cb(st_things_get_request_cb get_cb, st_things_set_request_cb set_cb);
 122
 123 /**
 124  * @brief Starts things stack.
 125  *            Parses the thing definition(whose path is passed to st_things_initialize(), configures the thing,
 126  *            creates the resources and prepares it for easy-setup.
 127  *            If easy-setup is not done yet, onboarding will be started using either SoftAP or BLE connection.
 128  *                Onboarding creates an ad-hoc network between the thing and the client for performing easy-setup.
 129  *            If easy-setup is already done, thing will be connected with the cloud.
 130  *            Application can know whether easy-setup is done or not through st_things_initialize API.
 131  *            Stack should have been initialized before calling this API.
 132  * @return @c 0 on success, otherwise a negative error value
 133  * @retval #ST_THINGS_ERROR_NONE Successful.
 134  *         It is also used for the case that the stack is started already.
 135  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 136  * @retval #ST_THINGS_ERROR_STACK_NOT_INITIALIZED Stack is not initialized.
 137  *         Initialize the stack by calling st_things_initialize().
 138  */
 139 int st_things_start(void);
 140
 141 /**
 142  * @brief Stops things stack.
 143  *            Removes all the data being used internally and releases all the memory allocated for the stack.
 144  *            Stack should have been initialized and started before calling this API.
 145  * @return @c 0 on success, otherwise a negative error value
 146  * @retval #ST_THINGS_ERROR_NONE Successful
 147  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 148  * @retval #ST_THINGS_ERROR_STACK_NOT_INITIALIZED Stack is not initialized.
 149  *         Initialize the stack by calling st_things_initialize().
 150  * @retval #ST_THINGS_ERROR_STACK_NOT_STARTED Stack is not started.
 151  *         Start the stack by calling st_things_start().
 152  */
 153 int st_things_stop(void);
 154
 155 /**
 156  * @brief Callback for getting user's opinion regarding device reset.
 157  * @return @c true to confirm, otherwise @c to deny
 158  */
 159 typedef bool (*st_things_reset_confirm_cb)(void);
 160
 161 /**
 162  * @brief Callback for carrying the result of reset.
 163  * @param[in] is_success Result of Stack-reset. (true : success, false : failure)
 164  */
 165 typedef void (*st_things_reset_result_cb)(bool is_success);
 166
 167 /**
 168  * @brief Callback registration function for Reset-Confirmation and Reset-Result functions.
 169  * @remarks Only one callback function can be set with this API.\n
 170  *          If multiple callbacks are set, the last one is registered only.\n
 171             And the callbacks are called in the internal thread, which is not detached,\n
 172  *          so application should return it to get the next callbacks.
 173  * @param[in] confirm_cb Callback function that will be called to get the user's input when reset is triggered.
 174  * @param[in] result_cb Callback function that will be called after the reset process is done.
 175  *                      This parameter can be NULL if notification for result of reset is not needed.
 176  * @return @c 0 on success, otherwise a negative error value
 177  * @retval #ST_THINGS_ERROR_NONE Successful
 178  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
 179  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 180  */
 181 int st_things_register_reset_cb(st_things_reset_confirm_cb confirm_cb, st_things_reset_result_cb result_cb);
 182
 183 /**
 184  * @brief Reset all the data related to security and cloud being used in the stack.
 185  *        Stack should have been initialized and started before calling this API.
 186  * @return @c 0 on success, otherwise a negative error value
 187  * @retval #ST_THINGS_ERROR_NONE Successful
 188  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 189  * @retval #ST_THINGS_ERROR_STACK_NOT_INITIALIZED Stack is not intialized.
 190  *         Initialize the stack by calling st_things_initialize().
 191  * @retval #ST_THINGS_ERROR_STACK_NOT_STARTED Stack is not started.
 192  *         Start the stack by calling st_things_start().
 193  */
 194 int st_things_reset(void);
 195
 196 /**
 197  * @brief Callback for carrying the randomly generated PIN info.
 198  * @details Device should show the PIN on display.
 199  * @param[in] pin_data PIN data in string format.
 200  * @param[in] pin_size Length of the PIN String.
 201  */
 202 typedef void (*st_things_pin_generated_cb)(const char *pin_data, const size_t pin_size);
 203
 204 /**
 205  * @brief Callback for informing the application to close the PIN display.
 206  */
 207 typedef void (*st_things_pin_display_close_cb)(void);
 208
 209 /**
 210  * @brief Callback registration function for getting randomly generated PIN for the PIN-Based Ownership Transfer Request.
 211  * @remarks Only one callback function can be set with this API.\n
 212  *          If multiple callbacks are set, the last one is registered only.\n
 213  *          And the callbacks are called in the internal thread, which is not detached,\n
 214  *          so application should return it to get the next callbacks.
 215  * @param[in] generated_cb Callback function that will be called when device receives a Ownership Transfer request from client.
 216  * @param[in] close_cb Callback function that will be called when Ownership Transfer is done so device can stop showing PIN on display.
 217  *                     This parameter can be NULL if stop triggering is not needed.
 218  * @return @c 0 on success, otherwise a negative error value
 219  * @retval #ST_THINGS_ERROR_NONE Successful
 220  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
 221  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 222  */
 223 int st_things_register_pin_handling_cb(st_things_pin_generated_cb generated_cb, st_things_pin_display_close_cb close_cb);
 224
 225 /**
 226  * @brief Callback for getting user's input regarding mutual verification.
 227  * @return @c true true in cse of confirmed, otherwise @c false
 228  */
 229 typedef bool (*st_things_user_confirm_cb)(void);
 230
 231 /**
 232  * @brief Callback registration function for getting user confirmation for MUTUAL VERIFICATION BASED JUST WORK Ownership transfer.
 233  * @remarks Only one callback function can be set with this API.\n
 234  *          If multiple callbacks are set, the last one is registered only.\n
 235  *          And the callbacks are called in the internal thread, which is not detached,\n
 236  *          so application should return it to get the next callbacks.
 237  * @param[in] confirm_cb Callback function that will be called when device receives a confirm request from client.
 238  * @return @c 0 on success, otherwise a negative error value
 239  * @retval #ST_THINGS_ERROR_NONE Successful
 240  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
 241  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 242  */
 243 int st_things_register_user_confirm_cb(st_things_user_confirm_cb confirm_cb);
 244
 245 /**
 246  * @brief Callback for getting the current state of ST Things.
 247  * @param[in]  things_status ST Things State
 248  */
 249 typedef void (*st_things_status_change_cb)(st_things_status_e things_status);
 250
 251 /**
 252  * @brief Callback registration function for getting notified when ST Things state changes.
 253  * @remarks Only one callback function can be set with this API.\n
 254  *          If multiple callbacks are set, the last one is registered only.\n
 255  *          And the callbacks are called in the internal thread, which is not detached,\n
 256  *          so application should return it to get the next callbacks.
 257  * @param[in] status_cb Refernce of the callback function to get ST Things status
 258  * @return @c 0 on success, otherwise a negative error value
 259  * @retval #ST_THINGS_ERROR_NONE Successful
 260  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
 261  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 262  */
 263 int st_things_register_things_status_change_cb(st_things_status_change_cb status_cb);
 264
 265 /**
 266  * @brief Notify the observers of a specific resource.
 267  *        Stack should have been initialized and started before calling this API.
 268  * @param[in]  resource_uri Resource URI of the resource which will be notified to observers.
 269  * @return @c 0 on success, otherwise a negative error value
 270  * @retval #ST_THINGS_ERROR_NONE Successful
 271  * @retval #ST_THINGS_ERROR_INVALID_PARAMETER Invalid parameter
 272  * @retval #ST_THINGS_ERROR_OPERATION_FAILED Operation failed
 273   * @retval #ST_THINGS_ERROR_STACK_NOT_INITIALIZED Stack is not intialized.
 274  *         Initialize the stack by calling st_things_initialize().
 275  * @retval #ST_THINGS_ERROR_STACK_NOT_STARTED Stack is not started.
 276  *         Start the stack by calling st_things_start().
 277  */
 278 int st_things_notify_observers(const char *resource_uri);
 279
 280 /**
 281  * @brief Create an instance of representation.
 282  * @remarks To destroy an instance, st_things_destroy_representation_inst() should be used.
 283  * @return a pointer of the created representation, otherwise a null pointer if the memory is insufficient.
 284  */
 285 st_things_representation_s *st_things_create_representation_inst(void);
 286
 287 /**
 288  * @brief Destroy an instance of representation.
 289  * @param[in]  rep Representation that will be destroyed.
 290  */
 291 void st_things_destroy_representation_inst(st_things_representation_s *rep);
 292
 293 #ifdef __cplusplus
 294 }
 295 #endif /* __cplusplus */
 296
 297 #endif /* __ST_THINGS_H__ */