inc/st_things_types.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_TYPES_H__
  18 #define __ST_THINGS_TYPES_H__
  19
  20 #include <stdint.h>
  21 #include <stdlib.h>
  22 #include <stdbool.h>
  23
  24 /**
  25  * @brief Enumeration for ST Things error code.
  26  */
  27 typedef enum {
  28     ST_THINGS_ERROR_NONE                         =  0, /**< Successful */
  29     ST_THINGS_ERROR_INVALID_PARAMETER            = -1, /**< Invalid parameter (If parameter is null or empty)*/
  30     ST_THINGS_ERROR_OPERATION_FAILED             = -2, /**< Operation Failed */
  31     ST_THINGS_ERROR_STACK_NOT_INITIALIZED        = -3, /**< Stack is not yet initialized*/
  32     ST_THINGS_ERROR_STACK_ALREADY_INITIALIZED    = -4, /**< Stack is already initialized*/
  33     ST_THINGS_ERROR_STACK_NOT_STARTED            = -5, /**< Stack is not yet started*/
  34     ST_THINGS_ERROR_STACK_RUNNING                = -6, /**< Stack is currently running*/
  35 } st_things_error_e;
  36
  37 /**
  38  * @brief Enumeration for ST Things status.
  39  */
  40 typedef enum {
  41     ST_THINGS_STATUS_INIT = 0,                         /**< Initial state of ST Things */
  42     ST_THINGS_STATUS_ES_STARTED,                       /**< Easy-setup is started */
  43     ST_THINGS_STATUS_ES_DONE,                          /**< Easy-setup is done */
  44     ST_THINGS_STATUS_ES_FAILED_ON_OWNERSHIP_TRANSFER,  /**< Easy-setup failed due to Ownership-Transfer failure */
  45     ST_THINGS_STATUS_CONNECTING_TO_AP,                 /**< Connecting to target Wi-Fi access point */
  46     ST_THINGS_STATUS_CONNECTED_TO_AP,                  /**< Connected to target Wi-Fi access point */
  47     ST_THINGS_STATUS_CONNECTING_TO_AP_FAILED,          /**< Failed to connect to target Wi-Fi access point */
  48     ST_THINGS_STATUS_REGISTERING_TO_CLOUD,             /**< Trying to Sign-up/Sign-in/Publish-Resource(s) to Cloud */
  49     ST_THINGS_STATUS_REGISTERED_TO_CLOUD,              /**< Publish resource(s) to cloud is complete. Now the Thing is ready to be controlled via Cloud */
  50     ST_THINGS_STATUS_REGISTERING_FAILED_ON_SIGN_IN,    /**< Failed to sign-in to Cloud */
  51     ST_THINGS_STATUS_REGISTERING_FAILED_ON_PUB_RES     /**< Failed to publish resources to Cloud */
  52 } st_things_status_e;
  53
  54 /**
  55  * @brief Structure for Representation.
  56  */
  57 typedef struct _st_things_representation
  58 {
  59     void*   payload; /**< Payload of representation */
  60
  61     /**
  62      * @brief API for getting the value of string type property with a key.
  63      * @remarks This API will return deep-copied string value as out parameter, so application must free it after use.
  64      * @param[in]  rep Instance of Representation.
  65      * @param[in]  key Property Name which represents the value.
  66      * @param[out] value String value
  67      * @return @c true if value exist, otherwise @c false
  68      */
  69     bool    (*get_str_value)            (struct _st_things_representation* rep, const char* key, char** value);
  70
  71     /**
  72      * @brief API for getting the value of boolean type property with a key.
  73      * @param[in]  rep Instance of Representation.
  74      * @param[in]  key Property Name which represents the value.
  75      * @param[out] value Bool value
  76      * @return @c true if value exist, otherwise @c false
  77      */
  78     bool    (*get_bool_value)           (struct _st_things_representation* rep, const char* key, bool* value);
  79
  80     /**
  81      * @brief API for getting the value of integer type property with a key.
  82      * @param[in]  rep Instance of Representation.
  83      * @param[in]  key Property Name which represents the value.
  84      * @param[out] value Integer value
  85      * @return @c true if value exist, otherwise @c false
  86      */
  87     bool    (*get_int_value)            (struct _st_things_representation* rep, const char* key, int64_t* value);
  88
  89     /**
  90      * @brief API for getting the value of double type property with a key.
  91      * @param[in]  rep Instance of Representation.
  92      * @param[in]  key Property Name which represents the value.
  93      * @param[out] value Double value
  94      * @return @c true if value exist, otherwise @c false
  95      */
  96     bool    (*get_double_value)         (struct _st_things_representation* rep, const char* key, double* value);
  97
  98     /**
  99      * @brief API for getting the value of byte array type property with a key.
 100      * @remarks This API will return deep-copied byte value as out parameter, so application must free it after use.
 101      * @param[in]  rep Instance of Representation.
 102      * @param[in]  key Property Name which represents the value.
 103      * @param[out] value Byte value
 104      * @param[out] size Size of Byte value
 105      * @return @c true if value exist, otherwise @c false
 106      */
 107     bool    (*get_byte_value)           (struct _st_things_representation* rep, const char* key, uint8_t** value, size_t* size);
 108
 109     /**
 110      * @brief API for getting the value of object type property with a key.
 111      * @remarks This API will return deep-copied object value as out parameter, so application must free it after use.\n
 112      *          To free an object, st_things_destroy_representation_inst() in st_things.h should be used.
 113      * @param[in]  rep Instance of Representation.
 114      * @param[in]  key Property Name which represents the value.
 115      * @param[out] value Object value
 116      * @return @c true if value exist, otherwise @c false
 117      */
 118     bool    (*get_object_value)         (struct _st_things_representation* rep, const char* key, struct _st_things_representation** value);
 119
 120     /**
 121      * @brief API for setting the value of string type property with a key.
 122      * @remarks This API will deep-copy the string value inside, so application still has an ownership of memory for the string value.
 123      * @param[in]  rep Instance of Representation.
 124      * @param[in]  key Property Name which will represent the value.
 125      * @param[in]  value String value.
 126      * @return @c true if setting value is successful, otherwise @c false
 127      */
 128     bool    (*set_str_value)            (struct _st_things_representation* rep, const char* key, const char* value);
 129
 130     /**
 131      * @brief API for setting the value of boolean type property with a key.
 132      * @param[in]  rep Instance of Representation.
 133      * @param[in]  key Property Name which will represent the value.
 134      * @param[in]  value Bool value.
 135      * @return @c true if setting value is successful, otherwise @c false
 136      */
 137     bool    (*set_bool_value)           (struct _st_things_representation* rep, const char* key, bool value);
 138
 139     /**
 140      * @brief API for setting the value of integer type property with a key.
 141      * @param[in]  rep Instance of Representation.
 142      * @param[in]  key Property Name which will represent the value.
 143      * @param[in]  value Integer value.
 144      * @return @c true if setting value is successful, otherwise @c false
 145      */
 146     bool    (*set_int_value)            (struct _st_things_representation* rep, const char* key, int64_t value);
 147
 148     /**
 149      * @brief API for setting the value of double type property with a key.
 150      * @param[in]  rep Instance of Representation.
 151      * @param[in]  key Property Name which will represent the value.
 152      * @param[in]  value Double value.
 153      * @return @c true if setting value is successful, otherwise @c false
 154      */
 155     bool    (*set_double_value)         (struct _st_things_representation* rep, const char* key, double value);
 156
 157     /**
 158      * @brief API for setting the value of byte array type property with a key.
 159      * @remarks This API will deep-copy the byte value inside, so application still has an ownership of memory for the byte value.
 160      * @param[in]  rep Instance of Representation.
 161      * @param[in]  key Property Name which will represent the value.
 162      * @param[in]  value Byte value.
 163      * @param[in]  size Size of Byte value.
 164      * @return @c true if setting value is successful, otherwise @c false
 165      */
 166     bool    (*set_byte_value)           (struct _st_things_representation* rep, const char* key, const uint8_t* value, size_t size);
 167
 168     /**
 169      * @brief API for setting the value of object type property with a key.
 170      * @remarks This API will deep-copy the object value inside, so application still has an ownership of memory for the object value.
 171      * @param[in]  rep Instance of Representation.
 172      * @param[in]  key Property Name which will represent the value.
 173      * @param[in]  value Object value.
 174      * @return @c true if value exist, otherwise @c false
 175      */
 176     bool    (*set_object_value)         (struct _st_things_representation* rep, const char* key, const struct _st_things_representation* value);
 177
 178     /**
 179      * @brief API for getting the value of string array type property with a key.
 180      * @remarks This API will return deep-copied array value as out parameter, so application must free it after use.
 181      * @param[in]  rep Instance of Representation.
 182      * @param[in]  key Property Name which will represent the array type of value.
 183      * @param[out] array Reference of the string array to where the value will be copied.
 184      * @param[out] length Total number of elements in the array.
 185      * @return @c true if value exist, otherwise @c false
 186      */
 187     bool    (*get_str_array_value)      (struct _st_things_representation* rep, const char* key, char*** array, size_t* length);
 188
 189     /**
 190      * @brief API for getting the value of integer array type property with a key.
 191      * @remarks This API will return deep-copied array value as out parameter, so application must free it after use.
 192      * @param[in]  rep Instance of Representation.
 193      * @param[in]  key Property Name which will represent the array type of value.
 194      * @param[out] array Reference of the integer array where the value will be copied.
 195      * @param[out] length Total number of elements in the array.
 196      * @return @c true if value exist, otherwise @c false
 197      */
 198     bool    (*get_int_array_value)      (struct _st_things_representation* rep, const char* key, int64_t** array, size_t* length);
 199
 200     /**
 201      * @brief API for getting the value of double array type property with a key.
 202      * @remarks This API will return deep-copied array value as out parameter, so application must free it after use.
 203      * @param[in]  rep Instance of Representation.
 204      * @param[in]  key Property Name which will represent the array type of value.
 205      * @param[out] array Reference of the double array where the value will be copied.
 206      * @param[out] length Total number of elements in the array.
 207      * @return @c true if value exist, otherwise @c false
 208      */
 209     bool    (*get_double_array_value)   (struct _st_things_representation* rep, const char* key, double** array, size_t* length);
 210
 211     /**
 212      * @brief API for getting the value of object array type property with a key.
 213      * @remarks This API will return deep-copied array value as out parameter, so application must free it after use.\n
 214      *          To free each object in array, st_things_destroy_representation_inst() in st_things.h should be used.
 215      * @param[in]  rep Instance of Representation.
 216      * @param[in]  key Property Name which represents the array type of value.
 217      * @param[out] array Reference of the object array where the value will be copied.
 218      * @param[out] length Total number of elements in the array.
 219      * @return @c true if value exist, otherwise @c false
 220      */
 221     bool    (*get_object_array_value)   (struct _st_things_representation* rep, const char* key, struct _st_things_representation*** array, size_t* length);
 222
 223     /**
 224      * @brief API for setting the value of string array type property with a key.
 225      * @remarks This API will deep-copy the array value inside, so application still has an ownership of memory for the array value.
 226      * @param[in]  rep Instance of Representation.
 227      * @param[in]  key Property Name which represents the value.
 228      * @param[in]  array String array type value.
 229      * @param[in]  length Total number of elements in the array.
 230      * @return @c true if setting value is successful, otherwise @c false
 231      */
 232     bool    (*set_str_array_value)      (struct _st_things_representation* rep, const char* key, const char** array, size_t length);
 233
 234     /**
 235      * @brief API for setting the value of integer array type property with a key.
 236      * @remarks This API will deep-copy the array value inside, so application still has an ownership of memory for the array value.
 237      * @param[in]  rep Instance of Representation.
 238      * @param[in]  key Property Name which represents the value.
 239      * @param[in]  array Integer array type value.
 240      * @param[in]  length Total number of elements in the array.
 241      * @return @c true if setting value is successful, otherwise @c false
 242      */
 243     bool    (*set_int_array_value)      (struct _st_things_representation* rep, const char* key, const int64_t* array, size_t length);
 244
 245     /**
 246      * @brief API for setting the value of double array type property with a key.
 247      * @remarks This API will deep-copy the array value inside, so application still has an ownership of memory for the array value.
 248      * @param[in]  rep Instance of Representation.
 249      * @param[in]  key Property Name which represents the value.
 250      * @param[in]  array Double array type value.
 251      * @param[in]  length Total number of elements in the array.
 252      * @return @c true if setting value is successful, otherwise @c false
 253      */
 254     bool    (*set_double_array_value)   (struct _st_things_representation* rep, const char* key, const double* array, size_t length);
 255
 256     /**
 257      * @brief API for setting the value of object array type property with a key.
 258      * @remarks This API will deep-copy the array value inside, so application still has an ownership of memory for the array value.
 259      * @param[in]  rep Instance of Representation.
 260      * @param[in]  key Property Name which represents the value.
 261      * @param[in]  array Object array type value.
 262      * @param[in]  length Total number of elements in the array.
 263      * @return @c true if setting value is successful, otherwise @c false
 264      */
 265     bool    (*set_object_array_value)   (struct _st_things_representation* rep, const char* key, const struct _st_things_representation** array, size_t length);
 266
 267 } st_things_representation_s;
 268
 269 /**
 270  * @brief Structure for representing the Get Request Message.
 271  */
 272 typedef struct _st_things_get_request_message
 273 {
 274     char*                               resource_uri;   /**< Resource URI */
 275     char*                               query;          /**< One or more query parameters of the request message. Ex: key1=value1;key2=value2;... */
 276     char*                               property_key;   /**< One or more property key that application needs to set a value for response. Ex: key1;key2;... */
 277
 278     /**
 279      * @brief API for getting the value of a specific query from the query parameters of the request.
 280      * @param[in]  req_msg Instance of get request message.
 281      * @param[in]  key Name of the query.(ex: key1, key2, etc)
 282      * @param[out] value Value of the query.(value1, value2, etc)
 283      * @return @c true if query exist, otherwise @c false
 284      */
 285     bool    (*get_query_value)          (struct _st_things_get_request_message* req_msg, const char* key, char** value);
 286
 287     /**
 288      * @brief API for checking whether the request has a specific property key or not.
 289      * @param[in]  req_msg Instance of get request message.
 290      * @param[in]  key Name of the property.
 291      * @return @c true if the property key exists, otherwise @c false
 292      */
 293     bool    (*has_property_key)         (struct _st_things_get_request_message* req_msg, const char* key);
 294
 295 } st_things_get_request_message_s;
 296
 297 /**
 298  * @brief Structure for representing the Set Request Message.
 299  */
 300 typedef struct _st_things_set_request_message
 301 {
 302     char*                               resource_uri;   /**< Resource URI */
 303     char*                               query;          /**< One or more query parameters of the request message. Ex: key1=value1?key2=value2?... */
 304     struct _st_things_representation*   rep;            /**< Representation of the set request message */
 305
 306     /**
 307      * @brief API for getting the value of a specific query from the query parameters of the request.
 308      * @param[in]  req_msg Instance of request message.
 309      * @param[in]  key Name of the query.(ex: key1, key2, etc)
 310      * @param[out] value Value of the query.(value1, value2, etc)
 311      * @return @c true if query exist, otherwise @c false
 312      */
 313     bool    (*get_query_value)          (struct _st_things_set_request_message* req_msg, const char* key, char** value);
 314
 315 } st_things_set_request_message_s;
 316
 317 #endif /* __ST_THINGS_TYPES_H__ */