inc/st_things_types.h

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