2 * Copyright (c) 2011-2015 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__
25 * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command
26 * @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.
39 * @brief The voice command handle.
42 typedef struct vc_cmd_s* vc_cmd_h;
45 * @brief The voice command list handle.
48 typedef struct vc_cmd_list_s* vc_cmd_list_h;
51 * @brief Called to retrieve The commands in list.
54 * @param[in] vc_command The command handle
55 * @param[in] user_data The user data passed from the foreach function
57 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
58 * @pre vc_cmd_list_foreach_commands() will invoke this callback.
60 * @see vc_cmd_list_foreach_commands()
62 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
66 * @brief Creates a handle for command list.
69 * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy().
71 * @param[out] vc_cmd_list The command list handle
73 * @return 0 on success, otherwise a negative error value
74 * @retval #VC_ERROR_NONE Successful
75 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
76 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
77 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
78 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
80 * @see vc_cmd_list_destroy()
82 int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list);
85 * @brief Destroys the handle for command list.
88 * @param[in] vc_cmd_list The command list handle
89 * @param[in] free_command The command free option @c true = release each commands in list,
90 * @c false = remove command from list
92 * @return 0 on success, otherwise a negative error value
93 * @retval #VC_ERROR_NONE Successful
94 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
95 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
96 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
98 * @see vc_cmd_list_create()
100 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
103 * @brief Gets command count of list.
106 * @param[in] vc_cmd_list The command list handle
107 * @param[out] count The count
109 * @return 0 on success, otherwise a negative error value
110 * @retval #VC_ERROR_NONE Successful
111 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
112 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
113 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
115 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
118 * @brief Adds command to command list.
121 * @param[in] vc_cmd_list The command list handle
122 * @param[in] vc_command The command handle
124 * @return 0 on success, otherwise a negative error value
125 * @retval #VC_ERROR_NONE Successful
126 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
127 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
128 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
130 * @see vc_cmd_list_remove()
132 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
135 * @brief Removes command from command list.
138 * @param[in] vc_cmd_list The command list handle
139 * @param[in] vc_command The command handle
141 * @return 0 on success, 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 * @see vc_cmd_list_add()
149 int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
152 * @brief Retrieves all commands of command list using callback function.
155 * @param[in] vc_cmd_list The command list handle
156 * @param[in] callback Callback function to invoke
157 * @param[in] user_data The user data to be passed to the callback function
159 * @return 0 on success, otherwise a negative error value
160 * @retval #VC_ERROR_NONE Successful
161 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
162 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
163 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
165 * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands.
167 * @see vc_cmd_list_cb()
169 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
172 * @brief Moves index to first command.
175 * @param[in] vc_cmd_list The command list handle
177 * @return 0 on success, otherwise a negative error value
178 * @retval #VC_ERROR_NONE Successful
179 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
180 * @retval #VC_ERROR_EMPTY List empty
181 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
182 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
184 * @see vc_cmd_list_last()
186 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
189 * @brief Moves index to last command.
192 * @param[in] vc_cmd_list The command list handle
194 * @return 0 on success, otherwise a negative error value
195 * @retval #VC_ERROR_NONE Successful
196 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
197 * @retval #VC_ERROR_EMPTY List empty
198 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
199 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
201 * @see vc_cmd_list_first()
203 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
206 * @brief Moves index to next command.
209 * @param[in] vc_cmd_list The command list handle
211 * @return 0 on success, otherwise a negative error value
212 * @retval #VC_ERROR_NONE Successful
213 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
214 * @retval #VC_ERROR_EMPTY List empty
215 * @retval #VC_ERROR_ITERATION_END List reached end
216 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
217 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
219 * @see vc_cmd_list_prev()
221 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
224 * @brief Moves index to previous command.
227 * @param[in] vc_cmd_list The command list handle
229 * @return 0 on success, otherwise a negative error value
230 * @retval #VC_ERROR_NONE Successful
231 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
232 * @retval #VC_ERROR_EMPTY List empty
233 * @retval #VC_ERROR_ITERATION_END List reached end
234 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
235 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
237 * @see vc_cmd_list_next()
239 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
242 * @brief Get current command from command list by index.
245 * @param[in] vc_cmd_list The command list handle
246 * @param[out] vc_command The command handle
248 * @return 0 on success, otherwise a negative error value
249 * @retval #VC_ERROR_NONE Successful
250 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
251 * @retval #VC_ERROR_EMPTY List empty
252 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
253 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
255 * @see vc_cmd_list_first()
256 * @see vc_cmd_list_last()
257 * @see vc_cmd_list_prev()
258 * @see vc_cmd_list_next()
260 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
264 * @brief Creates a handle for command.
267 * @remarks If the function succeeds, @a The command handle must be released
268 * with vc_cmd_destroy() or vc_cmd_list_destroy().
269 * You should set command and type if command is valid
271 * @param[out] vc_command The command handle
273 * @return 0 on success, otherwise a negative error value
274 * @retval #VC_ERROR_NONE Successful
275 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
276 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
277 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
278 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
280 * @see vc_cmd_destroy()
282 int vc_cmd_create(vc_cmd_h* vc_command);
285 * @brief Destroys the handle.
288 * @param[in] vc_command The command handle
290 * @return 0 on success, otherwise a negative error value
291 * @retval #VC_ERROR_NONE Successful
292 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
293 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
294 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
296 * @see vc_cmd_create()
298 int vc_cmd_destroy(vc_cmd_h vc_command);
301 * @brief Sets command.
304 * @param[in] vc_command The command handle
305 * @param[in] command The command text
307 * @return 0 on success, otherwise a negative error value
308 * @retval #VC_ERROR_NONE Successful
309 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
310 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
311 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
313 * @see vc_cmd_get_command()
315 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
318 * @brief Gets command.
321 * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL.
323 * @param[in] vc_command The command handle
324 * @param[out] command The command text
326 * @return 0 on success, otherwise a negative error value
327 * @retval #VC_ERROR_NONE Successful
328 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
329 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
330 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
332 * @see vc_cmd_set_command()
334 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
337 * @brief Sets command type.
340 * @remark If you do not set the command type, the default value is -1.
341 * You should set type if command is valid
343 * @param[in] vc_command The command handle
344 * @param[in] type The command type
346 * @return 0 on success, otherwise a negative error value
347 * @retval #VC_ERROR_NONE Successful
348 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
349 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
350 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
352 * @see vc_cmd_get_type()
354 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
357 * @brief Gets command type.
360 * @param[in] vc_command The command handle
361 * @param[out] type The command type
363 * @return 0 on success, 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
369 * @see vc_cmd_set_type()
371 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
382 #endif /* __VOICE_CONTROL_COMMAND_H__ */