include/voice_control_command.h

   1 /**
   2  * Copyright (c) 2011-2016 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  * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command
  25  * @ingroup CAPI_UIX_VOICE_CONTROL_MODULE
  26  *
  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.
  28  * @{
  29  */
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #endif
  35
  36
  37 /**
  38  * @brief Definition for fixed command format
  39  * @since_tizen 3.0
  40  */
  41 #define VC_CMD_FORMAT_FIXED     0
  42
  43 /**
  44  * @brief Definition for fixed and variable fixed command format
  45  * @since_tizen 3.0
  46  */
  47 #define VC_CMD_FORMAT_FIXED_AND_VFIXED  1
  48
  49 /**
  50  * @brief Definition for variable fixed and fixed command format
  51  * @since_tizen 3.0
  52  */
  53 #define VC_CMD_FORMAT_VFIXED_AND_FIXED  2
  54
  55 /**
  56  * @brief Definition for fixed and non-fixed command format
  57  * @since_tizen 3.0
  58  */
  59 #define VC_CMD_FORMAT_FIXED_AND_NONFIXED        3
  60
  61 /**
  62  * @brief Definition for non-fixed and fixed command format
  63  * @since_tizen 3.0
  64  */
  65 #define VC_CMD_FORMAT_NONFIXED_AND_FIXED        4
  66
  67
  68 /**
  69  * @brief The voice command handle.
  70  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  71  */
  72 typedef struct vc_cmd_s* vc_cmd_h;
  73
  74 /**
  75  * @brief The voice command list handle.
  76  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  77  */
  78 typedef struct vc_cmd_list_s* vc_cmd_list_h;
  79
  80 /**
  81  * @brief Called to retrieve The commands in list.
  82  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  83  *
  84  * @param[in] vc_command The command handle
  85  * @param[in] user_data The user data passed from the foreach function
  86  *
  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.
  89  *
  90  * @see vc_cmd_list_foreach_commands()
  91  */
  92 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
  93
  94
  95 /**
  96  * @brief Creates a handle for command list.
  97  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  98  *
  99  * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy().
 100  *
 101  * @param[out] vc_cmd_list The command list handle
 102  *
 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
 109  *
 110  * @see vc_cmd_list_destroy()
 111  */
 112 int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list);
 113
 114 /**
 115  * @brief Destroys the handle for command list.
 116  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 117  *
 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
 121  *
 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
 127  *
 128  * @see vc_cmd_list_create()
 129  */
 130 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
 131
 132 /**
 133  * @brief Gets command count of list.
 134  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 135  *
 136  * @param[in] vc_cmd_list The command list handle
 137  * @param[out] count The count
 138  *
 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
 144  */
 145 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
 146
 147 /**
 148  * @brief Adds command to command list.
 149  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 150  *
 151  * @param[in] vc_cmd_list The command list handle
 152  * @param[in] vc_command The command handle
 153  *
 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
 159  *
 160  * @see vc_cmd_list_remove()
 161  */
 162 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 163
 164 /**
 165  * @brief Removes command from command list.
 166  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 167  *
 168  * @param[in] vc_cmd_list The command list handle
 169  * @param[in] vc_command The command handle
 170  *
 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
 176  *
 177  * @see vc_cmd_list_add()
 178  */
 179 int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 180
 181 /**
 182  * @brief Retrieves all commands of command list using callback function.
 183  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 184  *
 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  *
 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
 194  *
 195  * @post        This function invokes vc_cmd_list_cb() repeatedly for getting commands.
 196  *
 197  * @see vc_cmd_list_cb()
 198  */
 199 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
 200
 201 /**
 202  * @brief Retrieves all commands on the system command list using a callback function.
 203  * @since_tizen 3.0
 204  *
 205  * @param[in] callback Callback function to invoke
 206  * @param[in] user_data The user data to be passed to the callback function
 207  *
 208  * @return 0 on success, otherwise a negative error value
 209  * @retval #VC_ERROR_NONE Successful
 210  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 211  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 212  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 213  *
 214  * @post This function invokes vc_cmd_list_cb() for each command.
 215  *
 216  * @see vc_cmd_list_cb()
 217  */
 218 int vc_cmd_list_foreach_system_command(vc_cmd_list_cb callback, void* user_data);
 219
 220 /**
 221  * @brief Moves index to first command.
 222  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 223  *
 224  * @param[in] vc_cmd_list The command list handle
 225  *
 226  * @return 0 on success, otherwise a negative error value
 227  * @retval #VC_ERROR_NONE Successful
 228  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #VC_ERROR_EMPTY List empty
 230  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 231  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 232  *
 233  * @see vc_cmd_list_last()
 234  */
 235 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
 236
 237 /**
 238  * @brief Moves index to last command.
 239  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 240  *
 241  * @param[in] vc_cmd_list The command list handle
 242  *
 243  * @return 0 on success, otherwise a negative error value
 244  * @retval #VC_ERROR_NONE Successful
 245  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #VC_ERROR_EMPTY List empty
 247  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 248  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 249  *
 250  * @see vc_cmd_list_first()
 251  */
 252 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
 253
 254 /**
 255  * @brief Moves index to next command.
 256  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 257  *
 258  * @param[in] vc_cmd_list The command list handle
 259  *
 260  * @return 0 on success, otherwise a negative error value
 261  * @retval #VC_ERROR_NONE Successful
 262  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 263  * @retval #VC_ERROR_EMPTY List empty
 264  * @retval #VC_ERROR_ITERATION_END List reached end
 265  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 266  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 267  *
 268  * @see vc_cmd_list_prev()
 269  */
 270 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
 271
 272 /**
 273  * @brief Moves index to previous command.
 274  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 275  *
 276  * @param[in] vc_cmd_list The command list handle
 277  *
 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_ITERATION_END List reached end
 283  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 284  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 285  *
 286  * @see vc_cmd_list_next()
 287  */
 288 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
 289
 290 /**
 291  * @brief Get current command from command list by index.
 292  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 293  *
 294  * @param[in] vc_cmd_list The command list handle
 295  * @param[out] vc_command The command handle
 296  *
 297  * @return 0 on success, otherwise a negative error value
 298  * @retval #VC_ERROR_NONE Successful
 299  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 300  * @retval #VC_ERROR_EMPTY List empty
 301  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 302  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 303  *
 304  * @see vc_cmd_list_first()
 305  * @see vc_cmd_list_last()
 306  * @see vc_cmd_list_prev()
 307  * @see vc_cmd_list_next()
 308  */
 309 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
 310
 311 /**
 312  * @brief Creates a handle for command.
 313  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 314  *
 315  * @remarks If the function succeeds, @a The command handle must be released
 316  *      with vc_cmd_destroy() or vc_cmd_list_destroy().
 317  *      You should set command and type if command is valid.
 318  *      The command format is set to #VC_CMD_FORMAT_FIXED by default and can be changed with vc_cmd_set_format().
 319  *
 320  * @param[out] vc_command The command handle
 321  *
 322  * @return 0 on success, otherwise a negative error value
 323  * @retval #VC_ERROR_NONE Successful
 324  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 325  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 326  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 327  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 328  *
 329  * @see vc_cmd_destroy()
 330  */
 331 int vc_cmd_create(vc_cmd_h* vc_command);
 332
 333 /**
 334  * @brief Destroys the handle.
 335  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 336  *
 337  * @param[in] vc_command The command handle
 338  *
 339  * @return 0 on success, otherwise a negative error value
 340  * @retval #VC_ERROR_NONE Successful
 341  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 343  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 344  *
 345  * @see vc_cmd_create()
 346  */
 347 int vc_cmd_destroy(vc_cmd_h vc_command);
 348
 349 /**
 350  * @brief Sets command or action.
 351  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 352  *
 353  * @param[in] vc_command The command handle
 354  * @param[in] command The command or action text
 355  *
 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
 361  *
 362  * @see vc_cmd_get_command()
 363  */
 364 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
 365
 366 /**
 367  * @brief Gets command.
 368  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 369  *
 370  * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL.
 371  *
 372  * @param[in] vc_command The command handle
 373  * @param[out] command The command text
 374  *
 375  * @return 0 on success, otherwise a negative error value
 376  * @retval #VC_ERROR_NONE Successful
 377  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 378  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 379  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 380  *
 381  * @see vc_cmd_set_command()
 382  */
 383 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
 384
 385 /**
 386  * @brief Gets the unfixed command.
 387  * @since_tizen 3.0
 388  *
 389  * @remark If the function succeeds, the @a command must be released with free() if it is not NULL.
 390  *      If the command of the given @a vc_command is NULL (@a vc_command is NOT NULL), @a command will be also NULL.
 391  *      This function should be used for commands which have non-fixed format.
 392  *
 393  * @param[in] vc_command The command handle
 394  * @param[out] command The unfixed command text
 395  *
 396  * @return 0 on success, 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 feature
 401  */
 402 int vc_cmd_get_unfixed_command(vc_cmd_h vc_command, char** command);
 403
 404 /**
 405  * @brief Sets command type.
 406  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 407  *
 408  * @remark If you do not set the command type, the default value is -1.
 409  *      You should set type if command is valid
 410  *
 411  * @param[in] vc_command The command handle
 412  * @param[in] type The command type
 413  *
 414  * @return 0 on success, otherwise a negative error value
 415  * @retval #VC_ERROR_NONE Successful
 416  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 417  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 418  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 419  *
 420  * @see vc_cmd_get_type()
 421  */
 422 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
 423
 424 /**
 425  * @brief Gets command type.
 426  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 427  *
 428  * @param[in] vc_command The command handle
 429  * @param[out] type The command type
 430  *
 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
 436  *
 437  * @see vc_cmd_set_type()
 438  */
 439 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
 440
 441 /**
 442  * @brief Sets the command format.
 443  * @since_tizen 3.0
 444  *
 445  * @remark The default format is #VC_CMD_FORMAT_FIXED.
 446  *
 447  * @param[in] vc_command The command handle
 448  * @param[in] format The command format
 449  *
 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
 455  *
 456  * @see vc_cmd_get_format()
 457  */
 458 int vc_cmd_set_format(vc_cmd_h vc_command, int format);
 459
 460 /**
 461  * @brief Gets the command format.
 462  * @since_tizen 3.0
 463  *
 464  * @remark The default format is #VC_CMD_FORMAT_FIXED.
 465  *
 466  * @param[in] vc_command The command handle
 467  * @param[out] format The command format
 468  *
 469  * @return 0 on success, otherwise a negative error value
 470  * @retval #VC_ERROR_NONE Successful
 471  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 472  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 473  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 474  *
 475  * @see vc_cmd_set_format()
 476  */
 477 int vc_cmd_get_format(vc_cmd_h vc_command, int* format);
 478
 479
 480 #ifdef __cplusplus
 481 }
 482 #endif
 483
 484 /**
 485  * @}@}
 486  */
 487
 488 #endif /* __VOICE_CONTROL_COMMAND_H__ */