include/voice_control_command.h

   1 /*
   2 * Copyright (c) 2011-2015 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17
  18 #ifndef __VOICE_CONTROL_COMMAND_H__
  19 #define __VOICE_CONTROL_COMMAND_H__
  20
  21 #include <tizen.h>
  22
  23
  24 /**
  25 * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command
  26 * @ingroup CAPI_UIX_VOICE_CONTROL_MODULE
  27 *
  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.
  29 * @{
  30 */
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #endif
  36
  37
  38 /**
  39 * @brief The voice command handle.
  40 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  41 */
  42 typedef struct vc_cmd_s* vc_cmd_h;
  43
  44 /**
  45 * @brief The voice command list handle.
  46 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  47 */
  48 typedef struct vc_cmd_list_s* vc_cmd_list_h;
  49
  50 /**
  51 * @brief Called to retrieve The commands in list.
  52 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  53 *
  54 * @param[in] vc_command The command handle
  55 * @param[in] user_data The user data passed from the foreach function
  56 *
  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.
  59 *
  60 * @see vc_cmd_list_foreach_commands()
  61 */
  62 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
  63
  64
  65 /**
  66 * @brief Creates a handle for command list.
  67 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  68 *
  69 * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy().
  70 *
  71 * @param[out] vc_cmd_list The command list handle
  72 *
  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
  79 *
  80 * @see vc_cmd_list_destroy()
  81 */
  82 int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list);
  83
  84 /**
  85 * @brief Destroys the handle for command list.
  86 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  87 *
  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
  91 *
  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
  97 *
  98 * @see vc_cmd_list_create()
  99 */
 100 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
 101
 102 /**
 103 * @brief Gets command count of list.
 104 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 105 *
 106 * @param[in] vc_cmd_list The command list handle
 107 * @param[out] count The count
 108 *
 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
 114 */
 115 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
 116
 117 /**
 118 * @brief Adds command to command list.
 119 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 120 *
 121 * @param[in] vc_cmd_list The command list handle
 122 * @param[in] vc_command The command handle
 123 *
 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
 129 *
 130 * @see vc_cmd_list_remove()
 131 */
 132 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 133
 134 /**
 135 * @brief Removes command from command list.
 136 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 137 *
 138 * @param[in] vc_cmd_list The command list handle
 139 * @param[in] vc_command The command handle
 140 *
 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
 146 *
 147 * @see vc_cmd_list_add()
 148 */
 149 int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 150
 151 /**
 152 * @brief Retrieves all commands of command list using callback function.
 153 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 154 *
 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
 158 *
 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
 164 *
 165 * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands.
 166 *
 167 * @see vc_cmd_list_cb()
 168 */
 169 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
 170
 171 /**
 172 * @brief Moves index to first command.
 173 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 174 *
 175 * @param[in] vc_cmd_list The command list handle
 176 *
 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
 183 *
 184 * @see vc_cmd_list_last()
 185 */
 186 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
 187
 188 /**
 189 * @brief Moves index to last command.
 190 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 191 *
 192 * @param[in] vc_cmd_list The command list handle
 193 *
 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
 200 *
 201 * @see vc_cmd_list_first()
 202 */
 203 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
 204
 205 /**
 206 * @brief Moves index to next command.
 207 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 208 *
 209 * @param[in] vc_cmd_list The command list handle
 210 *
 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
 218 *
 219 * @see vc_cmd_list_prev()
 220 */
 221 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
 222
 223 /**
 224 * @brief Moves index to previous command.
 225 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 226 *
 227 * @param[in] vc_cmd_list The command list handle
 228 *
 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
 236 *
 237 * @see vc_cmd_list_next()
 238 */
 239 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
 240
 241 /**
 242 * @brief Get current command from command list by index.
 243 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 244 *
 245 * @param[in] vc_cmd_list The command list handle
 246 * @param[out] vc_command The command handle
 247 *
 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
 254 *
 255 * @see vc_cmd_list_first()
 256 * @see vc_cmd_list_last()
 257 * @see vc_cmd_list_prev()
 258 * @see vc_cmd_list_next()
 259 */
 260 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
 261
 262
 263 /**
 264 * @brief Creates a handle for command.
 265 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 266 *
 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
 270 *
 271 * @param[out] vc_command The command handle
 272 *
 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
 279 *
 280 * @see vc_cmd_destroy()
 281 */
 282 int vc_cmd_create(vc_cmd_h* vc_command);
 283
 284 /**
 285 * @brief Destroys the handle.
 286 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 287 *
 288 * @param[in] vc_command The command handle
 289 *
 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
 295 *
 296 * @see vc_cmd_create()
 297 */
 298 int vc_cmd_destroy(vc_cmd_h vc_command);
 299
 300 /**
 301 * @brief Sets command.
 302 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 303 *
 304 * @param[in] vc_command The command handle
 305 * @param[in] command The command text
 306 *
 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
 312 *
 313 * @see vc_cmd_get_command()
 314 */
 315 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
 316
 317 /**
 318 * @brief Gets command.
 319 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 320 *
 321 * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL.
 322 *
 323 * @param[in] vc_command The command handle
 324 * @param[out] command The command text
 325 *
 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
 331 *
 332 * @see vc_cmd_set_command()
 333 */
 334 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
 335
 336 /**
 337 * @brief Sets command type.
 338 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 339 *
 340 * @remark If you do not set the command type, the default value is -1.
 341 *       You should set type if command is valid
 342 *
 343 * @param[in] vc_command The command handle
 344 * @param[in] type The command type
 345 *
 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
 351 *
 352 * @see vc_cmd_get_type()
 353 */
 354 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
 355
 356 /**
 357 * @brief Gets command type.
 358 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 359 *
 360 * @param[in] vc_command The command handle
 361 * @param[out] type The command type
 362 *
 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
 368 *
 369 * @see vc_cmd_set_type()
 370 */
 371 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
 372
 373
 374 #ifdef __cplusplus
 375 }
 376 #endif
 377
 378 /**
 379  * @}@}
 380  */
 381
 382 #endif /* __VOICE_CONTROL_COMMAND_H__ */