2 * Copyright (c) 2018 Samsung Electronics Co., Ltd.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __ST_THINGS_TYPES_H__
18 #define __ST_THINGS_TYPES_H__
25 * @brief Enumeration for ST Things error code.
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*/
38 * @brief Enumeration for ST Things status.
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 */
55 * @brief Structure for Representation.
57 typedef struct _st_things_representation
59 void* payload; /**< Payload of representation */
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
69 bool (*get_str_value) (struct _st_things_representation* rep, const char* key, char** value);
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
78 bool (*get_bool_value) (struct _st_things_representation* rep, const char* key, bool* value);
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
87 bool (*get_int_value) (struct _st_things_representation* rep, const char* key, int64_t* value);
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
96 bool (*get_double_value) (struct _st_things_representation* rep, const char* key, double* value);
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
107 bool (*get_byte_value) (struct _st_things_representation* rep, const char* key, uint8_t** value, size_t* size);
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
118 bool (*get_object_value) (struct _st_things_representation* rep, const char* key, struct _st_things_representation** value);
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
128 bool (*set_str_value) (struct _st_things_representation* rep, const char* key, const char* value);
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
137 bool (*set_bool_value) (struct _st_things_representation* rep, const char* key, bool value);
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
146 bool (*set_int_value) (struct _st_things_representation* rep, const char* key, int64_t value);
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
155 bool (*set_double_value) (struct _st_things_representation* rep, const char* key, double value);
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
166 bool (*set_byte_value) (struct _st_things_representation* rep, const char* key, const uint8_t* value, size_t size);
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
176 bool (*set_object_value) (struct _st_things_representation* rep, const char* key, const struct _st_things_representation* value);
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
187 bool (*get_str_array_value) (struct _st_things_representation* rep, const char* key, char*** array, size_t* length);
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
198 bool (*get_int_array_value) (struct _st_things_representation* rep, const char* key, int64_t** array, size_t* length);
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
209 bool (*get_double_array_value) (struct _st_things_representation* rep, const char* key, double** array, size_t* length);
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
221 bool (*get_object_array_value) (struct _st_things_representation* rep, const char* key, struct _st_things_representation*** array, size_t* length);
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
232 bool (*set_str_array_value) (struct _st_things_representation* rep, const char* key, const char** array, size_t length);
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
243 bool (*set_int_array_value) (struct _st_things_representation* rep, const char* key, const int64_t* array, size_t length);
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
254 bool (*set_double_array_value) (struct _st_things_representation* rep, const char* key, const double* array, size_t length);
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
265 bool (*set_object_array_value) (struct _st_things_representation* rep, const char* key, const struct _st_things_representation** array, size_t length);
267 } st_things_representation_s;
270 * @brief Structure for representing the Get Request Message.
272 typedef struct _st_things_get_request_message
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;... */
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
285 bool (*get_query_value) (struct _st_things_get_request_message* req_msg, const char* key, char** value);
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
293 bool (*has_property_key) (struct _st_things_get_request_message* req_msg, const char* key);
295 } st_things_get_request_message_s;
298 * @brief Structure for representing the Set Request Message.
300 typedef struct _st_things_set_request_message
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 */
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
313 bool (*get_query_value) (struct _st_things_set_request_message* req_msg, const char* key, char** value);
315 } st_things_set_request_message_s;
317 #endif /* __ST_THINGS_TYPES_H__ */