2 * Copyright (c) 2011-2016 Samsung Electronics Co., Ltd All Rights Reserved
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.
18 #ifndef __VOICE_CONTROL_COMMAND_H__
19 #define __VOICE_CONTROL_COMMAND_H__
24 * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command
25 * @ingroup CAPI_UIX_VOICE_CONTROL_MODULE
27 * @brief The @ref CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE API provides functions for creating/destroying command list and add/remove/retrieve commands of list.
38 * @brief Definition for fixed command format
41 #define VC_COMMAND_FORMAT_FIXED 0
44 * @brief Definition for fixed and variable fixed command format
47 #define VC_COMMAND_FORMAT_FIXED_AND_VFIXED 1
50 * @brief Definition for variable fixed and fixed command format
53 #define VC_COMMAND_FORMAT_VFIXED_AND_FIXED 2
56 * @brief Definition for fixed and non-fixed command format
59 #define VC_COMMAND_FORMAT_FIXED_AND_NONFIXED 3
62 * @brief Definition for non-fixed and fixed command format
65 #define VC_COMMAND_FORMAT_NONFIXED_AND_FIXED 4
69 * @brief The voice command handle.
70 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
72 typedef struct vc_cmd_s* vc_cmd_h;
75 * @brief The voice command list handle.
76 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
78 typedef struct vc_cmd_list_s* vc_cmd_list_h;
81 * @brief Called to retrieve The commands in list.
82 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
84 * @param[in] vc_command The command handle
85 * @param[in] user_data The user data passed from the foreach function
87 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
88 * @pre vc_cmd_list_foreach_commands() will invoke this callback.
90 * @see vc_cmd_list_foreach_commands()
92 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
96 * @brief Creates a handle for command list.
97 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
99 * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy().
101 * @param[out] vc_cmd_list The command list handle
103 * @return 0 on success, otherwise a negative error value
104 * @retval #VC_ERROR_NONE Successful
105 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
106 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
107 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
108 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
110 * @see vc_cmd_list_destroy()
112 int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list);
115 * @brief Destroys the handle for command list.
116 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
118 * @param[in] vc_cmd_list The command list handle
119 * @param[in] free_command The command free option @c true = release each commands in list,
120 * @c false = remove command from list
122 * @return 0 on success, otherwise a negative error value
123 * @retval #VC_ERROR_NONE Successful
124 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
125 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
126 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
128 * @see vc_cmd_list_create()
130 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
133 * @brief Gets command count of list.
134 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
136 * @param[in] vc_cmd_list The command list handle
137 * @param[out] count The count
139 * @return 0 on success, otherwise a negative error value
140 * @retval #VC_ERROR_NONE Successful
141 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
142 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
143 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
145 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
148 * @brief Adds command to command list.
149 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
151 * @param[in] vc_cmd_list The command list handle
152 * @param[in] vc_command The command handle
154 * @return 0 on success, otherwise a negative error value
155 * @retval #VC_ERROR_NONE Successful
156 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
157 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
158 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
160 * @see vc_cmd_list_remove()
162 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
165 * @brief Removes command from command list.
166 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
168 * @param[in] vc_cmd_list The command list handle
169 * @param[in] vc_command The command handle
171 * @return 0 on success, otherwise a negative error value
172 * @retval #VC_ERROR_NONE Successful
173 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
174 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
175 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
177 * @see vc_cmd_list_add()
179 int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
182 * @brief Retrieves all commands of command list using callback function.
183 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
185 * @param[in] vc_cmd_list The command list handle
186 * @param[in] callback Callback function to invoke
187 * @param[in] user_data The user data to be passed to the callback function
189 * @return 0 on success, otherwise a negative error value
190 * @retval #VC_ERROR_NONE Successful
191 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
192 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
193 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
195 * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands.
197 * @see vc_cmd_list_cb()
199 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
202 * @brief Moves index to first command.
203 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
205 * @param[in] vc_cmd_list The command list handle
207 * @return 0 on success, otherwise a negative error value
208 * @retval #VC_ERROR_NONE Successful
209 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
210 * @retval #VC_ERROR_EMPTY List empty
211 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
212 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
214 * @see vc_cmd_list_last()
216 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
219 * @brief Moves index to last command.
220 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
222 * @param[in] vc_cmd_list The command list handle
224 * @return 0 on success, otherwise a negative error value
225 * @retval #VC_ERROR_NONE Successful
226 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
227 * @retval #VC_ERROR_EMPTY List empty
228 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
229 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
231 * @see vc_cmd_list_first()
233 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
236 * @brief Moves index to next command.
237 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
239 * @param[in] vc_cmd_list The command list handle
241 * @return 0 on success, otherwise a negative error value
242 * @retval #VC_ERROR_NONE Successful
243 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
244 * @retval #VC_ERROR_EMPTY List empty
245 * @retval #VC_ERROR_ITERATION_END List reached end
246 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
247 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
249 * @see vc_cmd_list_prev()
251 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
254 * @brief Moves index to previous command.
255 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
257 * @param[in] vc_cmd_list The command list handle
259 * @return 0 on success, otherwise a negative error value
260 * @retval #VC_ERROR_NONE Successful
261 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
262 * @retval #VC_ERROR_EMPTY List empty
263 * @retval #VC_ERROR_ITERATION_END List reached end
264 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
265 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
267 * @see vc_cmd_list_next()
269 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
272 * @brief Get current command from command list by index.
273 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
275 * @param[in] vc_cmd_list The command list handle
276 * @param[out] vc_command The command handle
278 * @return 0 on success, otherwise a negative error value
279 * @retval #VC_ERROR_NONE Successful
280 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
281 * @retval #VC_ERROR_EMPTY List empty
282 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
283 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
285 * @see vc_cmd_list_first()
286 * @see vc_cmd_list_last()
287 * @see vc_cmd_list_prev()
288 * @see vc_cmd_list_next()
290 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
293 * @brief Creates a handle for command.
294 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
296 * @remarks If the function succeeds, @a The command handle must be released
297 * with vc_cmd_destroy() or vc_cmd_list_destroy().
298 * You should set command and type if command is valid.
299 * The command format is set to #VC_COMMAND_FORMAT_FIXED by default and can be changed with vc_cmd_set_format().
301 * @param[out] vc_command The command handle
303 * @return 0 on success, otherwise a negative error value
304 * @retval #VC_ERROR_NONE Successful
305 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
306 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
307 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
308 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
310 * @see vc_cmd_destroy()
312 int vc_cmd_create(vc_cmd_h* vc_command);
315 * @brief Destroys the handle.
316 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
318 * @param[in] vc_command The command handle
320 * @return 0 on success, otherwise a negative error value
321 * @retval #VC_ERROR_NONE Successful
322 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
323 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
324 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
326 * @see vc_cmd_create()
328 int vc_cmd_destroy(vc_cmd_h vc_command);
331 * @brief Sets command or action.
332 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
334 * @param[in] vc_command The command handle
335 * @param[in] command The command or action text
337 * @return 0 on success, otherwise a negative error value
338 * @retval #VC_ERROR_NONE Successful
339 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
340 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
341 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
343 * @see vc_cmd_get_command()
345 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
348 * @brief Gets command.
349 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
351 * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL.
353 * @param[in] vc_command The command handle
354 * @param[out] command The command text
356 * @return 0 on success, otherwise a negative error value
357 * @retval #VC_ERROR_NONE Successful
358 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
359 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
360 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
362 * @see vc_cmd_set_command()
364 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
367 * @brief Gets the unfixed command.
370 * @remark If the function succeeds, the @a command must be released with free() if it is not NULL.
371 * If the command of the given @a vc_command is NULL (@a vc_command is NOT NULL), @a command will be also NULL.
372 * This function should be used for commands which have non-fixed format.
374 * @param[in] vc_command The command handle
375 * @param[out] command The unfixed command text
377 * @return 0 on success, otherwise a negative error value
378 * @retval #VC_ERROR_NONE Successful
379 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
380 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
381 * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
383 int vc_cmd_get_unfixed_command(vc_cmd_h vc_command, char** command);
386 * @brief Sets command type.
387 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
389 * @remark If you do not set the command type, the default value is -1.
390 * You should set type if command is valid
392 * @param[in] vc_command The command handle
393 * @param[in] type The command type
395 * @return 0 on success, otherwise a negative error value
396 * @retval #VC_ERROR_NONE Successful
397 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
398 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
399 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
401 * @see vc_cmd_get_type()
403 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
406 * @brief Gets command type.
407 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
409 * @param[in] vc_command The command handle
410 * @param[out] type The command type
412 * @return 0 on success, otherwise a negative error value
413 * @retval #VC_ERROR_NONE Successful
414 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
416 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
418 * @see vc_cmd_set_type()
420 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
423 * @brief Sets the command format.
426 * @remark The default format is #VC_COMMAND_FORMAT_FIXED.
428 * @param[in] vc_command The command handle
429 * @param[in] format The command format
431 * @return 0 on success, otherwise a negative error value
432 * @retval #VC_ERROR_NONE Successful
433 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
434 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
435 * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
437 * @see vc_cmd_get_format()
439 int vc_cmd_set_format(vc_cmd_h vc_command, int format);
442 * @brief Gets the command format.
445 * @remark The default format is #VC_COMMAND_FORMAT_FIXED.
447 * @param[in] vc_command The command handle
448 * @param[out] format The command format
450 * @return 0 on success, otherwise a negative error value
451 * @retval #VC_ERROR_NONE Successful
452 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
453 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
454 * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
456 * @see vc_cmd_set_format()
458 int vc_cmd_get_format(vc_cmd_h vc_command, int* format);
469 #endif /* __VOICE_CONTROL_COMMAND_H__ */