1 /* ****************************************************************
3 * Copyright 2017 Samsung Electronics All Rights Reserved.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 ******************************************************************/
21 #ifndef __ST_THINGS_TYPES_H__
22 #define __ST_THINGS_TYPES_H__
29 * @brief Enumeration for ST Things error code.
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*/
42 * @brief Enumeration for ST Things status.
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 */
59 * @brief Structure for Representation.
61 typedef struct _st_things_representation
63 void* payload; /**< Payload of representation */
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
73 bool (*get_str_value) (struct _st_things_representation* rep, const char* key, char** value);
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
82 bool (*get_bool_value) (struct _st_things_representation* rep, const char* key, bool* value);
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
91 bool (*get_int_value) (struct _st_things_representation* rep, const char* key, int64_t* value);
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
100 bool (*get_double_value) (struct _st_things_representation* rep, const char* key, double* value);
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
111 bool (*get_byte_value) (struct _st_things_representation* rep, const char* key, uint8_t** value, size_t* size);
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
122 bool (*get_object_value) (struct _st_things_representation* rep, const char* key, struct _st_things_representation** value);
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
132 bool (*set_str_value) (struct _st_things_representation* rep, const char* key, const char* value);
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
141 bool (*set_bool_value) (struct _st_things_representation* rep, const char* key, bool value);
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
150 bool (*set_int_value) (struct _st_things_representation* rep, const char* key, int64_t value);
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
159 bool (*set_double_value) (struct _st_things_representation* rep, const char* key, double value);
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
170 bool (*set_byte_value) (struct _st_things_representation* rep, const char* key, const uint8_t* value, size_t size);
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
180 bool (*set_object_value) (struct _st_things_representation* rep, const char* key, const struct _st_things_representation* value);
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
191 bool (*get_str_array_value) (struct _st_things_representation* rep, const char* key, char*** array, size_t* length);
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
202 bool (*get_int_array_value) (struct _st_things_representation* rep, const char* key, int64_t** array, size_t* length);
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
213 bool (*get_double_array_value) (struct _st_things_representation* rep, const char* key, double** array, size_t* length);
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
225 bool (*get_object_array_value) (struct _st_things_representation* rep, const char* key, struct _st_things_representation*** array, size_t* length);
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
236 bool (*set_str_array_value) (struct _st_things_representation* rep, const char* key, const char** array, size_t length);
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
247 bool (*set_int_array_value) (struct _st_things_representation* rep, const char* key, const int64_t* array, size_t length);
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
258 bool (*set_double_array_value) (struct _st_things_representation* rep, const char* key, const double* array, size_t length);
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
269 bool (*set_object_array_value) (struct _st_things_representation* rep, const char* key, const struct _st_things_representation** array, size_t length);
271 } st_things_representation_s;
274 * @brief Structure for representing the Get Request Message.
276 typedef struct _st_things_get_request_message
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;... */
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
289 bool (*get_query_value) (struct _st_things_get_request_message* req_msg, const char* key, char** value);
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
297 bool (*has_property_key) (struct _st_things_get_request_message* req_msg, const char* key);
299 } st_things_get_request_message_s;
302 * @brief Structure for representing the Set Request Message.
304 typedef struct _st_things_set_request_message
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 */
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
317 bool (*get_query_value) (struct _st_things_set_request_message* req_msg, const char* key, char** value);
319 } st_things_set_request_message_s;
321 #endif /* __ST_THINGS_TYPES_H__ */