inc/st_things.h

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