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__
26 * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command
27 * @ingroup CAPI_UIX_VOICE_CONTROL_MODULE
28 * @brief The @ref CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE API provides functions for creating/destroying command list and add/remove/retrieve commands of list.
40 * @brief Definition for fixed command format.
43 #define VC_COMMAND_FORMAT_FIXED 0
47 * @brief Definition for fixed and variable fixed command format.
50 #define VC_COMMAND_FORMAT_FIXED_AND_VFIXED 1
54 * @brief Definition for variable fixed and fixed command format.
57 #define VC_COMMAND_FORMAT_VFIXED_AND_FIXED 2
61 * @brief Definition for fixed and non-fixed command format.
64 #define VC_COMMAND_FORMAT_FIXED_AND_NONFIXED 3
68 * @brief Definition for non-fixed and fixed command format.
71 #define VC_COMMAND_FORMAT_NONFIXED_AND_FIXED 4
75 * @brief The voice command handle.
76 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
78 typedef struct vc_cmd_s* vc_cmd_h;
82 * @brief The voice command list handle.
83 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
85 typedef struct vc_cmd_list_s* vc_cmd_list_h;
89 * @brief Called to retrieve The commands in list.
90 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
91 * @param[in] vc_command The command handle
92 * @param[in] user_data The user data passed from the foreach function
93 * @return @c true to continue with the next iteration of the loop,
94 * @c false to break out of the loop
95 * @pre vc_cmd_list_foreach_commands() will invoke this callback.
96 * @see vc_cmd_list_foreach_commands()
98 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
102 * @brief Creates a handle for command list.
103 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
104 * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy().
105 * @param[out] vc_cmd_list The command list handle
106 * @return @c 0 on success,
107 * otherwise a negative error value
108 * @retval #VC_ERROR_NONE Successful
109 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
110 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
111 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
112 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
113 * @see vc_cmd_list_destroy()
115 int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list);
119 * @brief Destroys the handle for command list.
120 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
121 * @param[in] vc_cmd_list The command list handle
122 * @param[in] free_command The command free option @c true = release each commands in list,
123 * @c false = remove command from list
124 * @return @c 0 on success,
125 * otherwise a negative error value
126 * @retval #VC_ERROR_NONE Successful
127 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
128 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
129 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
130 * @see vc_cmd_list_create()
132 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
136 * @brief Gets command count of list.
137 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
138 * @param[in] vc_cmd_list The command list handle
139 * @param[out] count The count
140 * @return @c 0 on success,
141 * otherwise a negative error value
142 * @retval #VC_ERROR_NONE Successful
143 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
144 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
145 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
147 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
151 * @brief Adds command to command list.
152 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
153 * @param[in] vc_cmd_list The command list handle
154 * @param[in] vc_command The command handle
155 * @return @c 0 on success,
156 * otherwise a negative error value
157 * @retval #VC_ERROR_NONE Successful
158 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
159 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
160 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
161 * @see vc_cmd_list_remove()
163 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
167 * @brief Removes command from command list.
168 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
169 * @param[in] vc_cmd_list The command list handle
170 * @param[in] vc_command The command handle
171 * @return @c 0 on success,
172 * otherwise a negative error value
173 * @retval #VC_ERROR_NONE Successful
174 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
175 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
176 * @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);
183 * @brief Retrieves all commands of command list using callback function.
184 * @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
188 * @return @c 0 on success,
189 * 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
194 * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands.
195 * @see vc_cmd_list_cb()
197 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
201 * @brief Moves index to first command.
202 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
203 * @param[in] vc_cmd_list The command list handle
204 * @return @c 0 on success,
205 * otherwise a negative error value
206 * @retval #VC_ERROR_NONE Successful
207 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
208 * @retval #VC_ERROR_EMPTY List empty
209 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
210 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
211 * @see vc_cmd_list_last()
213 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
217 * @brief Moves index to last command.
218 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
219 * @param[in] vc_cmd_list The command list handle
220 * @return @c 0 on success,
221 * otherwise a negative error value
222 * @retval #VC_ERROR_NONE Successful
223 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
224 * @retval #VC_ERROR_EMPTY List empty
225 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
226 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
227 * @see vc_cmd_list_first()
229 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
233 * @brief Moves index to next command.
234 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
235 * @param[in] vc_cmd_list The command list handle
236 * @return @c 0 on success,
237 * otherwise a negative error value
238 * @retval #VC_ERROR_NONE Successful
239 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
240 * @retval #VC_ERROR_EMPTY List empty
241 * @retval #VC_ERROR_ITERATION_END List reached end
242 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
243 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
244 * @see vc_cmd_list_prev()
246 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
250 * @brief Moves index to previous command.
251 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
252 * @param[in] vc_cmd_list The command list handle
253 * @return @c 0 on success,
254 * otherwise a negative error value
255 * @retval #VC_ERROR_NONE Successful
256 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
257 * @retval #VC_ERROR_EMPTY List empty
258 * @retval #VC_ERROR_ITERATION_END List reached end
259 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
260 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
261 * @see vc_cmd_list_next()
263 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
267 * @brief Get current command from command list by index.
268 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
269 * @param[in] vc_cmd_list The command list handle
270 * @param[out] vc_command The command handle
271 * @return @c 0 on success,
272 * otherwise a negative error value
273 * @retval #VC_ERROR_NONE Successful
274 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
275 * @retval #VC_ERROR_EMPTY List empty
276 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
277 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
278 * @see vc_cmd_list_first()
279 * @see vc_cmd_list_last()
280 * @see vc_cmd_list_prev()
281 * @see vc_cmd_list_next()
283 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
287 * @brief Creates a handle for command.
288 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
289 * @remarks If the function succeeds, @a The command handle must be released
290 * with vc_cmd_destroy() or vc_cmd_list_destroy().
291 * You should set command and type if command is valid.
292 * The command format is set to #VC_COMMAND_FORMAT_FIXED by default and can be changed with vc_cmd_set_format().
293 * @param[out] vc_command The command handle
294 * @return @c 0 on success,
295 * otherwise a negative error value
296 * @retval #VC_ERROR_NONE Successful
297 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
298 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
299 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
300 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
301 * @see vc_cmd_destroy()
303 int vc_cmd_create(vc_cmd_h* vc_command);
307 * @brief Destroys the handle.
308 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
309 * @param[in] vc_command The command handle
310 * @return @c 0 on success,
311 * otherwise a negative error value
312 * @retval #VC_ERROR_NONE Successful
313 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
314 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
315 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
316 * @see vc_cmd_create()
318 int vc_cmd_destroy(vc_cmd_h vc_command);
322 * @brief Sets command or action.
323 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
324 * @param[in] vc_command The command handle
325 * @param[in] command The command or action text
326 * @return @c 0 on success,
327 * otherwise a negative error value
328 * @retval #VC_ERROR_NONE Successful
329 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
330 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
331 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
332 * @see vc_cmd_get_command()
334 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
338 * @brief Gets command.
339 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
340 * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL.
341 * @param[in] vc_command The command handle
342 * @param[out] command The command text
343 * @return @c 0 on success,
344 * otherwise a negative error value
345 * @retval #VC_ERROR_NONE Successful
346 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
347 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
348 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
349 * @see vc_cmd_set_command()
351 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
355 * @brief Gets the unfixed command.
357 * @remark If the function succeeds, the @a command must be released with free() if it is not NULL.
358 * If the command of the given @a vc_command is NULL (@a vc_command is NOT NULL), @a command will be also NULL.
359 * This function should be used for commands which have non-fixed format.
360 * @param[in] vc_command The command handle
361 * @param[out] command The unfixed command text
362 * @return @c 0 on success,
363 * otherwise a negative error value
364 * @retval #VC_ERROR_NONE Successful
365 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
366 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
367 * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
369 int vc_cmd_get_unfixed_command(vc_cmd_h vc_command, char** command);
373 * @brief Sets command type.
374 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
375 * @remark If you do not set the command type, the default value is @c -1.
376 * You should set type if command is valid
377 * @param[in] vc_command The command handle
378 * @param[in] type The command type
379 * @return @c 0 on success,
380 * otherwise a negative error value
381 * @retval #VC_ERROR_NONE Successful
382 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
383 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
384 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
385 * @see vc_cmd_get_type()
387 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
391 * @brief Gets command type.
392 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
393 * @param[in] vc_command The command handle
394 * @param[out] type The command type
395 * @return @c 0 on success,
396 * otherwise a negative error value
397 * @retval #VC_ERROR_NONE Successful
398 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
399 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
400 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
401 * @see vc_cmd_set_type()
403 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
407 * @brief Sets the command format.
409 * @remark The default format is #VC_COMMAND_FORMAT_FIXED.
410 * @param[in] vc_command The command handle
411 * @param[in] format The command format
412 * @return @c 0 on success,
413 * otherwise a negative error value
414 * @retval #VC_ERROR_NONE Successful
415 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
416 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
417 * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
418 * @see vc_cmd_get_format()
420 int vc_cmd_set_format(vc_cmd_h vc_command, int format);
424 * @brief Gets the command format.
426 * @remark The default format is #VC_COMMAND_FORMAT_FIXED.
427 * @param[in] vc_command The command handle
428 * @param[out] format The command format
429 * @return @c 0 on success,
430 * otherwise a negative error value
431 * @retval #VC_ERROR_NONE Successful
432 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
433 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
434 * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
435 * @see vc_cmd_set_format()
437 int vc_cmd_get_format(vc_cmd_h vc_command, int* format);
450 #endif /* __VOICE_CONTROL_COMMAND_H__ */